octopus-workflow/core/skills/release/SKILL.md

---
name: release
description: >
  Use ONLY when ready to cut a release. The Release Manager (Worker) inspects
  project state (git log, version files, build) to determine the semver bump,
  generate the changelog, tag, and produce a release artifact. Works on any
  project state — no pipeline artifacts required.
triggers:
  - release
  - cut release
  - 发版
  - publish release
  - ship release
role: Producer
---

> Core 中立版（Increment 6a 改写，原 deferHard verbatimDir）。机制、结构与 frontmatter 保持；实例术语（工具名、路径、工单号）按 `core/adapters/TERMINOLOGY.md` 绑定到具体实例。
# Release

Prepare and tag a release based on project facts — git history since the last
tag, current version, build status, and dependency health. No dependency on `.artifacts/{slug}/`
(**deprecated** — SDLC artifacts now live in the Gitea wiki at `{slug}/...`;
see `_shared/gitea-read-patterns.md`) or any pipeline skill outputs.

**This SKILL does not deploy.** Deployment is project-specific (K8s, Docker,
npm publish, etc.) and varies too widely to template. The release artifact
produced here is the input to project-specific deployment workflows.

## Agent Role

The release is owned and executed by the **Release Manager** (Worker).

**Context compaction**: release is a pipeline stage boundary. The main session
compacts at this clean boundary ONLY when a capacity/projection trigger holds,
per `core/rules/compact.md` §"Stage-boundary compaction" (long multi-stage
runs — DAG Epic orchestration — keep the legacy every-boundary compaction;
short runs — bugfix / DAG task — and standalone runs default to NOT
compacting). The Release Manager itself is single-phase and
artifact-driven (version files, changelog, tag); a mid-run compaction loses
nothing — re-read the release checklist state and git log to resume.

---

## Preconditions

Before starting the release:

- [ ] Working tree is clean (`git status` has no uncommitted changes).
- [ ] `core/checklists/release.md` is accessible.

---

## Phase 1 — Pre-release Gate

Run each check against the live project. Stop and report failures.

1. **Clean workspace**: `git status` must show nothing to commit.
2. **Branch**: confirm the current branch. Default assumption: release from
   `main` or `master`. If on another branch, note it.
3. **Build**: run the project's build command. Must pass.
4. **Typecheck + Lint**: run the project's typecheck and lint. Must pass.
5. **Tests**: run the project's test suite. Must pass.
6. **Dependency audit**: run the project's vulnerability scanner
   (e.g. `npm audit`, `bun audit`, `pip-audit`, `cargo audit`).
   - No new HIGH or CRITICAL CVEs block the release.
   - Pre-existing HIGH/CRITICAL CVEs do NOT block but **MUST be filed as
     tech-debt** before the release lands. File them in TWO TIERS (batching
     rule, [org-internal #3846] — a single release audit once fanned out to 14 TDs → 14 PRs → 
     56-84 CI runs on a saturated runner pool): Tier A below is the general
     mechanical-change batching rule; Tier B and the escape hatch follow it.

<a id="phase-1-tier-a"></a>
### Tier A — 通用机械变更并单规则 / Universal mechanical-change batching rule

Origin [org-internal #3846] (audit-batch pilot, generalized in place): the rule covers ANY
single-source fan-out of mechanical changes, not just dependency audits.
Two source types today: (a) dependency bump audits; (b) docs 批量修订
(batch docs revisions).

#### 规则正文 / Rule text

- **Core**: mechanical changes of ONE class fanning out from a single
  source are filed as ONE batch issue + ONE batch PR — never N×issue +
  N×PR. The batch body keeps one row per item (per-CVE / per-doc mapping),
  so per-item traceability is unchanged; work the batch as a single PR.
- **(a) Dependency bump audits** (the [org-internal #3846] origin case): advisories whose
  remediation is a plain version bump (lockfile-only diff, no semver-major
  jump, no overrides/catalog surgery, no API or adapter fallout) are filed
  together via `工单 API（见 TERMINOLOGY）create` with
  `title="[{origin}] audit-batch@{version}: mechanical bumps for {N} advisories (TD-{NNN})"`
  and labels `[tech_debt_label_id, severity_label_id, kind_bug_label_id]`
  (severity = highest in the batch). One row per advisory — CVE/GHSA ID,
  affected package + from→to version, severity (CVSS), advisory URL,
  recommended remediation, and a per-advisory Reactivation Trigger
  ("resolved when `npm audit` / `bun audit` reports no HIGH/CRITICAL for
  this advisory") — so the release-notes `TD-NNN → #NNNN` mapping stays
  per-advisory.
- **(b) Docs 批量修订 (batch docs revisions)**: many small same-class docs
  corrections discovered in one pass (e.g. a terminology sweep) file as ONE
  issue via the same flow,
  `title="[{origin}] docs-batch: {class} revisions for {N} files"`, with one
  row per file (path, correction, reason); same ONE-batch-PR landing.
- **Landing**: when members live on separate branches, compose the single
  batch PR via the `land-batch` skill (`core/skills/land-batch/SKILL.md`
  — cross-branch batch composition, topology B). For dependency-bump
  batches pass `batch-compose --convergent bun.lock` (script
  `.gitea/scripts/batch-compose.ts`): the regenerable lockfile is exempt
  from path-overlap admission and lockfile-only conflicts are surgically
  resolved to the running head's version.

#### 适用边界 / Applicability boundary

- **非mechanical（含判断成分的变更，不并单）** — items requiring judgment
  (wording decisions, behavior/API changes, review-dependent edits) are
  never batched; file each as its own issue.
- **路径重叠（batch 成员触碰相同文件 → 不并单；唯一豁免 =
  可再生共享文件`bun.lock` 经batch-compose `--convergent` 收敛）** — the sole
  path-overlap exemption is the regenerable shared lockfile under
  `--convergent`; every other same-file collision stays un-batched.
- **semver-major 跳变 / overrides·catalog 手术 / adapter·peer 联动（→ 
  Tier B 独立单，维持 per-package）** — these stay per-package Tier B
  issues. Tier B and the escape hatch (below) survive this generalization
  unchanged.

#### 降级路径 / Degradation path

- **并单 PR CI 失败 → 按锁文件 hunk 拆包回退（bisect）**: for dependency
  batches, bisect by splitting lockfile hunks per package back into
  per-package PRs — the original Tier A bisect semantics carried over
  verbatim (同语义，泛化措辞: every mechanical batch degrades the same way).
- **Docs batches**: split per file back into per-file PRs.
- **land-batch composition fallback** (exit codes per
  `.gitea/scripts/batch-compose.ts`): `3` path-overlap → split the batch
  along the reported pairs (or land the overlapping member 1:1) and re-run
  per group; `4` merge conflict / `5` transport/git error → fall back to
  1:1 PRs for the whole batch.
- **Preflight hedge ([org-internal #3846])**: run `bun install --dry-run` before opening
  a dependency-batch PR — the resolver accepting the composed version set
  is a cheap pre-CI rejection of impossible bump combinations.

Tier B and the escape hatch (unchanged by the generalization):

- **Tier B — surgery, one issue per package**: semver-major jumps,
  adapter/peer fallout, or overrides/catalog surgery keep the
  per-package issue: `title="[{origin}] {CVE-ID/GHSA-ID} in {package} (TD-{NNN})"`
  with the same labels; body requirements match the Tier A rows.
- Escape hatch: either tier may carve a single advisory into its own
  issue when same-day remediation is required (urgent HIGH/CRITICAL).

De-duplicate against open `tech-debt` issues (match by
CVE/GHSA ID) before creating. Record the `TD-NNN → #NNNN` mapping in the
release notes. See `verify` Phase 5.5 for the tech-debt promotion body
template and `_shared/gitea-write-patterns.md` Pattern 3.

```markdown
## Pre-release Gate

| Check             | Status                                                |
| ----------------- | ----------------------------------------------------- |
| Clean workspace   | ✅/ ❌                                              |
| Branch            | {branch name}                                         |
| Build             | ✅/ ❌                                              |
| Typecheck + Lint  | ✅/ ❌                                              |
| Tests             | ✅/ ❌(N passed, M failed)                           |
| Dependency audit  | ✅/ ⚠️ N known CVEs (pre-existing) / ❌N new CVEs   |
```

If any gate fails except known CVEs, stop and report what failed.

---

## Phase 2 — Version Bump

Determine the new version by inspecting git history since the last tag.

1. **Find last tag**: `git describe --tags --abbrev=0` (or `git tag --sort=-v:refname | head -1`).
   - **No previous tag?** This is the first tracked release. Use the initial commit as
     baseline: `git rev-list --max-parents=0 HEAD`. After tagging this release, create
     a retroactive baseline tag (`v{base-version}`) on the initial commit so future
     cycles have a clean `{tag}..{tag}` range. Document the gap in the release report.
2. **Read commits since last tag**: `git log <last-tag>..HEAD --oneline`.
3. **Read current version** from the project's version file (`package.json`
   `version`, `Cargo.toml`, `VERSION`, etc.).
4. **Categorize commits** by change type:

   | Conventional prefix  | Semver  | Examples                      |
   | -------------------- | ------- | ----------------------------- |
   | `BREAKING CHANGE:` / `!:` | MAJOR | API removal, schema change    |
   | `feat:`              | MINOR   | New feature, new endpoint     |
   | `fix:`               | PATCH   | Bug fix only                  |
   | `perf:`              | PATCH   | Performance improvement       |
   | `refactor:`          | PATCH   | Internal restructuring        |
   | `docs:` / `chore:`   | (skip)  | Not user-visible              |

   If no conventional prefix found, infer from the subject line:
   - "add", "implement", "introduce" → MINOR
   - "fix", "resolve", "correct" → PATCH
   - "remove", "drop", "rename" (public API) → MAJOR

5. **Compute bump**:
   - If any MAJOR commit → bump MAJOR.
   - Else if any MINOR commit → bump MINOR.
   - Else → bump PATCH.

```markdown
## Version Bump

**Last tag**: {tag}
**Current version**: {old version}
**New version**: {new version}
**Type**: MAJOR / MINOR / PATCH
**Commits since last tag**: {N}
**Reason**: {justification — e.g. "2 feat + 3 fix → MINOR"}
```

---

## Phase 3 — Changelog

Generate the changelog from `git log <last-tag>..HEAD`:

1. **List all commits**. For each, extract:
   - Type (from prefix or inferred).
   - Scope (if present, e.g. `feat(auth):`).
   - Description (the subject line, past tense, human-readable).
2. **Group by type**:
   - **Added** — `feat:` commits.
   - **Changed** — modifications to existing behavior (non-breaking).
   - **Fixed** — `fix:` commits.
   - **Breaking** — `BREAKING CHANGE:` or `!:` commits.
3. **Deduplicate**: squash multiple commits for the same change into one entry
   where it makes narrative sense.
4. Read the existing root `CHANGELOG.md` (if any) and prepend this release.

Write to root `CHANGELOG.md` (prepend section).

```markdown
## [{version}] — {YYYY-MM-DD}

### Added

- {feature} ({commit hash short})

### Changed

- {change} ({hash})

### Fixed

- {bugfix} ({hash})

### Breaking

- {breaking change} ({hash}) — see migration notes above
```

---

## Phase 4 — Tag & Finalize

1. **Update version file** — write the new version to the project's version
   manifest.
2. **Commit**: `git add` version file + changelog file, commit with message:
   ```
   release: {version}
   ```
3. **Tag**: `git tag v{version}` (adjust prefix per project convention —
   check existing tags with `git tag -l`).
4. **Verify tag**: `git tag -l v{version}` confirms the tag exists.

**Do not push** — the user must explicitly request pushing to remote.

```markdown
## Release Artifact

- **Version**: {version}
- **Commit**: {commit hash}
- **Tag**: v{version}
- **Changelog**: CHANGELOG.md updated

### Files Changed

| File           | Change                    |
| -------------- | ------------------------- |
| {version file} | {old} → {new}             |
| CHANGELOG.md   | Prepended {version}       |
```

---

## Phase 4b — Publish Release Artifacts (octopus project, manual)

> Octopus-specific. Other projects: substitute your own artifact pipeline —
> the goal is identical (turn the tag into downloadable assets).

The CI publish pipeline (`.gitea/workflows/publish.yml`) was **retired by
[org-internal #2003]** (138/138 historical runs cancelled; the pipeline sat unused for 35+
days). Releasing octopus is now a **manual local process**. All former CI
steps live in repo scripts, runnable from a maintainer machine with the right
credentials in the environment.

### Prerequisites

- Clean checkout of the release commit (tag pushed or about to be pushed).
- Credentials in env:
  - `GITEA_TOKEN` — PAT with `write:repository` (release create/undraft,
    tag push) and `write:package` (container registry). The `CI_PAT` secret
    value is the canonical token.
  - `NODE_AUTH_TOKEN` — only if publishing to npm.
  - `AUR_KEY` — only if pushing the AUR package.
  - Docker logged in to the Gitea container registry:
    `echo "$GITEA_TOKEN" | docker login <instance-registry-host> -u <user> --password-stdin`.

### Steps

1. **Version + draft release** (idempotent — skips if already published):
   ```bash
   GITEA_TOKEN=<pat> GH_REPO=Octopus/octopus bun script/version.ts
   ```
   Creates (or refines) the draft Gitea release for `v{version}`.

2. **Build the 12 platform binaries + archives** (longest step):
   ```bash
   OCTOPUS_VERSION={version} OCTOPUS_RELEASE={release-id} \
     GH_REPO=Octopus/octopus GITEA_TOKEN=<pat> \
     bun <harness-package>/script/build.ts
   ```
   `build.ts` attaches the 12 release assets to the draft release.

3. **Publish npm / docker / AUR + git sync**:
   ```bash
   OCTOPUS_VERSION={version} OCTOPUS_RELEASE={release-id} \
     GITEA_TOKEN=<pat> GH_REPO=Octopus/octopus \
     NODE_AUTH_TOKEN=<npm-token> \
     bun script/publish.ts
   ```
   Set `OCTOPUS_GITEA_ONLY=true` to skip npm/docker/AUR/homebrew.

4. **Undraft the release** (makes it public):
   ```bash
   curl -fsS -X PATCH \
     "<instance-base-url>/api/v1/repos/Octopus/octopus/releases/{release-id}" \
     -H "Authorization: token $GITEA_TOKEN" \
     -H "Content-Type: application/json" -d '{"draft": false}'
   ```

5. **Verify assets** — the release must carry 12 assets:
   ```bash
   curl -sS "<instance-base-url>/api/v1/repos/Octopus/octopus/releases/tags/v{version}" \
     -H "Authorization: token $GITEA_TOKEN" | jq '.assets | length'
   ```

6. **Sync the public mirror repo** (`Octopus/octopus-release`):
   ```bash
   CI_PAT=<pat> VERSION={version} bash script/sync-public-install.sh
   CI_PAT=<pat> VERSION={version} bash script/sync-public-assets.sh
   CI_PAT=<pat> VERSION={version} bash script/verify-public-sync.sh
   ```

### Notes

- **Windows code-signing** is not provisioned (no Windows runner / Azure
  Trusted Signing); the CLI ships unsigned, as before ([org-internal #252]).
- **Rollback**: if a step fails mid-release, the draft release + tag can be
  deleted and re-run; every script above is idempotent or safely re-runnable.
- If a future CI pipeline replaces this manual flow, update this section and
  reference [org-internal #2003] for the retirement rationale.

---

## Phase 5 — Rollback Plan

Document how to undo this release:

1. **Git rollback**:
   - `git tag -d v{version}` (if not yet pushed).
   - `git revert {commit_hash}` (if already merged).
   - If the release includes DB migrations, confirm the `down` migration exists.
2. **Data rollback** (if applicable):
   - For each migration, confirm the `down` migration exists and has been tested.
   - If the release changes data format without a reversible migration, mark
     `⚠️ IRREVERSIBLE DATA CHANGE`.

```markdown
## Rollback Plan

### Git Rollback

git tag -d v{version}
# or: git revert {hash}

### Data Rollback
- Migration `{name}`: down {exists / NOT FOUND}
- {additional risks}

### Rollback Triggers
| Condition          | Threshold    | Duration |
| ------------------ | ------------ | -------- |
| P99 latency spike  | 2x baseline  | 5 min    |
| Error rate spike   | 1%           | 1 min    |
| Critical bug       | Data loss / security breach | immediate |
```

---

## Phase 6 — Post-release Smoke Test

1. Run the project's build command on the tagged commit. Must pass.
2. Run the test suite. Must pass.
3. Return to the branch: `git checkout <original-branch>`.

---

## Phase 7 — Report

```markdown
## Release Report

**Version**: {old} → {new} (MAJOR / MINOR / PATCH)
**Tag**: v{version}
**Commits**: {N} since last tag ({feat} features, {fix} fixes)
**Typecheck**: ✅| Lint: ✅| Tests: ✅

### Changelog

{paste changelog section}

### Release Artifacts

- Commit: {hash} — `release: {version}`
- Tag: v{version}
- Changelog: CHANGELOG.md updated

---

**Deploy**: {manual step — "merge to main triggers CI", etc.}
**Rollback**: see Phase 5 above
**Next**: `core/skills/retrospective/SKILL.md` (optional — run on any project state)
```

---

## References

- `core/checklists/release.md` — Release checklist
- Semver spec: https://semver.org
- Conventional Commits: https://www.conventionalcommits.org