oxideterm-release

# OxideTerm Release

Publish an OxideTerm release through the repository-owned automation. Treat the user's completed GUI run as the release gate and do not run Cargo tests by default.

## Required release input

Resolve these values before making release changes:

- Target version.
- Target channel: `stable`, `beta`, or `gpui-preview`.
- Explicit confirmation that the user ran the GUI application and approved publishing.
- Release-note detail level when the user explicitly requests `minimal`, `medium`, or `detailed`; otherwise use `detailed`.

Infer the channel only when the version is unambiguous. Ask before publishing if GUI approval is absent. Preparing a changelog or dry run does not require approval.

## Channel contract

| Channel | Version | Tag | Changelog | Base notes |
|---|---|---|---|---|
| Stable | `X.Y.Z` | `vX.Y.Z` | `.github/release-notes/stable-changelog.md` | `.github/release-notes/stable.md` |
| Beta | `X.Y.Z-beta.N` | `vX.Y.Z-beta.N` | `.github/release-notes/beta-changelog.md` | `.github/release-notes/beta.md` |
| GPUI preview | `X.Y.Z-gpui-preview.N` | `gpui-vX.Y.Z-gpui-preview.N` | `.github/release-notes/gpui-preview-changelog.md` | `.github/release-notes/gpui-preview.md` |

Do not invent another tag prefix. The native package workflow receives the existing tag through its `release_tag` dispatch input and selects release notes from that tag.

## Workflow

### 1. Inspect repository state

Work from the OxideTerm repository root. Read `AGENTS.md`, then inspect:

```bash
git status --short --branch
git remote -v
git log -10 --oneline --decorate
```

Fetch the publishing remote and tags before deciding that a tag is available:

```bash
git fetch origin --tags
```

Confirm the branch is not behind or diverged from its upstream, and inspect the target tag locally and remotely:

```bash
git rev-list --left-right --count HEAD...@{upstream}
git tag --list <tag>
git ls-remote --tags origin refs/tags/<tag> refs/tags/<tag>^{}
```

Preserve unrelated user changes. Stop if the intended release scope cannot be separated safely or the branch has diverged. For an ordinary release, stop when the target tag exists. Only move an existing tag through the explicit canceled-release recovery procedure below.

### 2. Establish the changelog range

Run the bundled helper before writing the changelog:

```bash
python3 .agents/skills/oxideterm-release/scripts/release_context.py \
  --repo . --channel <channel> --version <version>
```

Prefer the previous reachable tag from the same channel as the baseline:

- Stable compares with the previous stable tag.
- Beta compares with the previous beta tag.
- GPUI preview compares with the previous GPUI preview tag.

For the first release in a channel, use the newest reachable release tag from any of the three channels as the bootstrap baseline. Use the root commit only when the repository has no earlier reachable release tag. This keeps a first beta or preview changelog scoped to work since the actual preceding release instead of summarizing the entire repository.

The helper prints the exact range, commits, and diff summary. Also inspect actual changes, including intended uncommitted changes:

```bash
git diff <previous-tag>..HEAD
git diff
git diff --cached
```

Do not derive release notes from commit subjects alone. Read the meaningful implementation and user-facing differences. Exclude mechanical version bumps, changelog edits, formatting-only churn, and internal details that have no release impact.

### 3. Write the channel changelog

Insert `## <version>` as the newest entry in the selected changelog. The heading must exactly match the version because `.github/scripts/compose_release_notes.py` uses it to locate the entry. The heading is an extraction boundary, not necessarily part of the published release body.

Write every version entry as two complete language blocks in this order:

```markdown
## <version>

### English

<English summary and sections>

### 中文

<Chinese summary and sections>
```

Keep both blocks structurally aligned: they must describe the same outcomes, limitations, validation status, and upgrade requirements in the same order. Translate for natural release-note language rather than word for word, and keep product names, commands, file names, and protocol names unchanged when translation would reduce precision. Do not merge English and Chinese into the same bullet. Use concise user-facing past tense in English and concise completed-action wording in Chinese. Keep each language's opening summary paragraph on one physical line so the GitHub Release editor does not show an artificial break. Combine related commits into one outcome and avoid raw commit-title dumps, implementation trivia, unsupported performance claims, and claims that were not verified. Use one restrained, semantically relevant emoji on each main stable-release section heading in both blocks; do not decorate every bullet or mix multiple emoji styles within one section.

For a fork release, each language block must clearly separate changes inherited from official OxideTerm upstream from changes implemented by the fork. Use explicit localized headings equivalent to `Upstream changes` / `上游更新` and `Fork-specific changes` / `Fork 自有更新`; subsystem headings may be nested below them when the selected detail level warrants it. Classify merged or cherry-picked official work as upstream regardless of commit author, and classify behavior unique to the publishing fork as fork-specific. When a fork modifies an upstream feature, describe the inherited capability under upstream and the fork's material delta under fork-specific changes. If either category has no changes in the release range, state that explicitly instead of omitting the category. Never let a combined summary or bullet imply that the fork authored upstream work.

#### Release-note detail level

Use the same level for the English and Chinese blocks. The levels control coverage and grouping, not a mandatory word co