AGENT SKILL

release

Read before any release work — instant builds, nightlies, stable tags, publishing, release workflows — or symbolizing a user's crash log.

License 许可
Apache-2.0
所属仓库
clice-io/clice
最近更新
2026-11-15
Stars
★ 1.4k
Forks
89

01 前言 Front Matter

name
release
description
Read before any release work — instant builds, nightlies, stable tags, publishing, release workflows — or symbolizing a user's crash log.

03 SKILL.md 正文

Releases

Versioning

One version number everywhere: git tag vX.Y.Z == extension version == release page. Odd minor = pre-release channel, even minor = stable (the VS Code Marketplace convention). Nightlies compute X.<odd>.YYYYMMDDHH (UTC hour) on the odd minor above the newest release — 0.1.* today, 0.3.* after stable v0.2.0 — so nobody edits version numbers by hand. The versions in bazel/workspace_status.mjs, pixi.toml, and editors/vscode/package.json are permanent placeholders (0.1.0); the real version is injected from the tag at build time (binary via git describe, vsix via CI). A local vsce publish with the placeholder is rejected by the Marketplace — that is intentional accident protection. Open VSX has no such guard: a local pixi run publish-ovsx publishes the placeholder version for real, so leave Open VSX to CI.

Tier 1 — Instant builds (every green CI run)

Nothing to operate. Every main push and PR run repackages the test-suite binaries (no strip) into vsix-build-<target> workflow artifacts, and the raw binaries are in build-<triple>-<type> artifacts. To hand a fix to a user: point them at the run's artifact (GitHub login required), or have them set clice.executable to the extracted binary.

Tier 2 — Nightly (pre-release channel)

nightly.yml runs daily (cron) or via gh workflow run nightly.yml: skips when main has no new commits, otherwise tags the nightly version and promotes — nothing is rebuilt. Every main CI run already packages the binaries its test suites validated (the build jobs build the packages); nightly picks the newest main commit whose green run still has live package artifacts (path-filtered runs such as docs-only commits build nothing), tags exactly that commit, downloads its packages, attaches them to a GitHub pre-release plus the Marketplace and Open VSX pre-release channels, and prunes odd-minor pre-releases older than 30 days or beyond the newest 25 (the Zed extension reads only the first 30 releases, which must keep the newest stable one), sparing the release mason-org/mason-registry pins in packages/clice/package.yaml — Mason's Renovate bumps that pin only to stable releases. Promotion fails loudly if no packaged green run exists. A nightly can tag only a commit whose .github/workflows/ are main's: GitHub refuses GITHUB_TOKEN any other, since a tag makes its commit's workflows runnable. Every change to them builds (main.yml's path filter) and every main commit gets a run of its own, so the pick lacks them only while that change's main run is red or still running; the nightly then fails before tagging, naming the change: rerun its run green (gh run rerun <id> --failed), or wait for it. Once tagged, it dispatches the ecosystem round (ecosystem.yml, ecosystem/README.md) on that commit with the packages' CI run: every real project's regression and perf jobs, report only; perf measures clice against the nightly before (what clice spends a tenth more of is listed), on Sundays against clangd. A failed nightly just means no nightly that day — fix main and rerun via dispatch, with the maintainer's approval like any release trigger.

Every GitHub release, nightly or stable, is created as a draft and published by publish-clice.yml only once all six platform archives are attached: drafts are hidden from anyone without push access, so no user's editor extension ever installs from a half-uploaded release. A failed promote job leaves the draft behind; gh run rerun <id> --failed finishes and publishes it.

The vsix packaging matrix runs in parallel, but release upload and registry publishing happen in one serial job (publish-release) with 5 attempts per vsix — concurrent publishes trip Marketplace internal errors (TF400898). Open VSX (org secret UPLOAD_VSX_EXT, namespace clice-io) publishes the same vsix after the Marketplace step and runs even when that step failed, so neither registry blocks the other; it checks the token with ovsx verify-pat first and is skipped with a notice when the secret is empty. The job is rerun-safe: gh run rerun <id> --failed re-uploads with --clobber and skips already-published versions, so a transient registry failure is recovered by rerunning just that job — never by a new tag.

The binary embeds its build identity (git describe: nearest tag + commit hash), not the release tag — the tag is applied after the build. Match crash logs to releases by the commit hash; the release notes state the hash.

Tier 3 — Stable release (manual, even minor)

Every step that tags or publishes needs the maintainer's explicit approval first.

  1. Freeze: stop merging features; the last nightlies of the freeze are the RCs.
  2. When a nightly is judged good — its ecosystem round shows no new failure: every job green, a job whose failures the project already knows (its known issues) green too — dispatch its round against clangd and read its perf tables: gh workflow run ecosystem.yml --ref main -f run=<its CI run> -f clangd=true (the round reads the run's build-* artifacts, which live three days: for an older nightly, rerun its main workflow first). Then tag its commit: git tag v0.2.0 <commit> && git push origin v0.2.0. The tag push runs the release path of main.yml, which promotes the already-tested packages from that commit's green CI run and publishes the extensions (Marketplace and Open VSX, without the pre-release flag). The promote path creates the GitHub release as a draft if none exists, and publishes it once every platform archive is attached; it refuses a release that is already published, so notes prepared on the releases page beforehand must be saved as a draft. Package artifacts expire 30 days after the CI run, so the tagged commit's run must be less than a month old — for an older commit, rerun its main workflow first to regenerate the packages.
  3. Write the release notes on the GitHub release page (the download table format from the nightly notes is a good template).
  4. Verify: assets present (6 packages + 6 symbol archives + 6 vsix), Marketplace and Open VSX show the new stable version.

Plumbing changes

There is no separate dry run: packaging runs on every CI build (the platforms of test.yml that package build //:package and //:symbols) and the vsix path runs as instant-vscode, so release plumbing is exercised by every code-touching PR. Only the promote/upload glue (publish-clice.yml, nightly orchestration) is release-time-only.

Crash log support

Ask the user for the log (the crashed process's .log from the session directory, printed at startup in the editor's clice output panel; by default .clice/logs/<session>/ in the project, under logging_dir when the settings name one). The crash section starts with clice <version> <target> and the link to the commit's source — download that release's *.symbols.tar.xz (.zip for Windows; GSYM) and run:

python scripts/symbolize.py crash.log --symbols clice.gsym

Every CI platform that packages runs this path on its own package: the package's clice crashes on purpose and its trace symbolizes against the symbol package (scripts/check_crash_symbols.py).

For core-dump-level debugging, fetch the full DWARF from the debug-info-* artifact of the main CI run that built the release (90-day retention; find it via the commit hash in the release notes). If the log predates the version line or the release was pruned, symbolization is not possible — ask the user to reproduce on a current nightly.

04 同仓库更多 Skills