​

Releasing and Changelog Guide

​

Versioning Rules

• Use the SemVer shape MAJOR.MINOR.PATCH, but apply it operationally in this repo.
• Keep one hard-coded SI version source of truth: root Cargo.toml under [workspace.package].version.
• Treat every other SI version surface as derived data from that root workspace version, not as an independently maintained version.
• Every commit must bump PATCH in the same commit.
• A published release bumps MINOR, resets PATCH to 0, and uses a release tag of vX.Y.0.
• Only minor release versions are tagged and published to GitHub Releases or external distribution channels.
• Use the v prefix consistently for release tags and GitHub Releases. The canonical release/tag form is vX.Y.0; bare forms such as 0.50.0 are non-canonical and must not be introduced.
• Patch versions such as vX.Y.1 remain commit-scoped working versions only. They are not release tags and must not have GitHub Release entries.
• There must be exactly one canonical GitHub Release per minor release tag. Do not leave duplicate release entries for both a bare tag and a v-prefixed tag on the same version line.
• MAJOR changes remain exceptional and must be called out explicitly when they happen.

​

Changelog Format (Predefined)

## [vX.Y.0] - YYYY-MM-DD
### Added
- ...
### Changed
- ...
### Fixed
- ...
### Removed
- ...
### Security
- ...

• Newest first.
• Use only the sections that apply.
• Short, user-facing bullets in past tense.
• Dates are UTC in YYYY-MM-DD.

​

Release Process (Best-Practice Sequence)

​

0) Pre-flight checks (clean repo, sync tags)

git status -sb
git fetch --tags origin
git switch main
git pull --ff-only

• Ensure CI is green on main.
• Ensure you can push tags and create GitHub releases.
• Ensure the working tree is clean and the branch is up to date.
• Make sure you have all remote tags locally before picking the next version.
• Inspect existing release/tag state before cutting a new release:

orbit github release list Aureuma/si --auth-mode oauth
git tag -l

• Confirm there are no stray patch-version releases such as vX.Y.1, no bare-tag releases such as 0.50.0, and no duplicate release entries for the same minor line.

​

1) Determine the next version + release name

• Decide the next release version vX.Y.0.
• Choose a short suggested name for the release title (e.g., “Safari Login Flow”).
• Title format for GitHub Release: vX.Y.0 - Suggested Name.
• Do not cut release tags or release titles in bare form such as 0.50.0 - Suggested Name.

​

2) Draft the changelog entry (authoritative notes)

1. Add a new entry to the top of CHANGELOG.md with today’s UTC date.
2. Summarize user-facing changes in 2–6 bullets.
3. Keep language past tense and user-focused.
4. Cover the full set of patch-bump commits since the previous minor release.

​

3) Bump version strings in code

• root Cargo.toml workspace.package.version = "X.Y.0"
• Cargo.lock follows that same workspace version update in the same commit.

​

4) Verify and commit the release prep

cargo run --quiet --locked --manifest-path rust/crates/si-tools/Cargo.toml --bin si-test-runner -- workspace
cargo run --quiet --locked -p si-cli -- build installer smoke-host
cargo run --quiet --locked -p si-cli -- build installer smoke-pnpm
cargo run --quiet --locked -p si-cli -- build installer smoke-homebrew
./.artifacts/cargo-target/release/si build self assets --out-dir .artifacts/release-preflight
./.artifacts/cargo-target/release/si build self verify --version vX.Y.0 --out-dir .artifacts/release-preflight
git add CHANGELOG.md Cargo.toml Cargo.lock
git commit -m "release: vX.Y.0"

• Keep release prep changes in a dedicated commit.
• The release-assets preflight confirms archive packaging before publishing a GitHub Release.
• si build self assets reads the canonical version from root Cargo.toml when --version is omitted.
• Include the pnpm smoke lane so user-owned global-prefix installs stay verified before release.
• Include the Homebrew smoke lane so the tap formula still installs the Rust-primary binary.

​

5) Create an annotated tag for the release commit

git tag -a vX.Y.0 -m "vX.Y.0"

• Annotated tags are recommended for releases and are the best practice (they store metadata like tagger, date, and message).
• Do not create patch tags such as vX.Y.1.
• Do not create bare tags such as X.Y.0.

​

6) Push commits and the new tag

git push
git push origin vX.Y.0

• Push the tag explicitly to avoid conflicts with existing tags.
• gh release create can auto-create a tag if it doesn’t exist; using --verify-tag ensures you only release a tag you already created and pushed.
• If you let gh release create auto-create a tag, fetch tags afterward to sync locally: git fetch --tags origin.
• If you do let it auto-create a tag, use --target <branch|sha> to pin the release to the desired commit.
• orbit github release create is stricter: it checks the remote tag first, creates the tag ref only when --target <sha> is provided, and otherwise fails clearly.

​

7) Prepare release notes and publish release

git log --oneline "$(git describe --tags --abbrev=0)..HEAD"

1. Extract the new vX.Y.0 section into release-notes.md (manual or script).
2. Create the release with a title and notes file:

orbit github release create Aureuma/si \
  --tag vX.Y.0 \
  --title "vX.Y.0 - Suggested Name" \
  --notes-file release-notes.md \
  --draft

3. If the tag is not pushed yet, use:

orbit github release create Aureuma/si \
  --tag vX.Y.0 \
  --title "vX.Y.0 - Suggested Name" \
  --notes-file release-notes.md \
  --target "$(git rev-parse HEAD)" \
  --draft

4. Equivalent gh fallback:

gh release create vX.Y.0 \\
  --title "vX.Y.0 - Suggested Name" \\
  --notes-file release-notes.md \\
  --verify-tag

gh release create vX.Y.0 \\
  --title "vX.Y.0 - Suggested Name" \\
  --notes-from-tag \\
  --verify-tag

• --notes-from-tag uses the annotated tag message when present; otherwise it falls back to the commit message. Option C: Use GitHub auto-generated release notes and prepend highlights.

gh release create vX.Y.0 \\
  --title "vX.Y.0 - Suggested Name" \\
  --generate-notes \\
  --notes-start-tag vA.B.0 \\
  --notes "Highlights:\\n- ...\\n- ..." \\
  --verify-tag

• --verify-tag aborts if the tag doesn’t already exist on the remote.
• --generate-notes uses GitHub’s Release Notes API and can be combined with --notes.
• Add --notes-start-tag vA.B.0 to define the start tag for generated notes when needed.
• Add --fail-on-no-commits if you want to prevent duplicate releases when there are no new commits.
• In an SI checkout, orbit github release create can omit the repo argument entirely and infer it from origin.
• If you omit --title, SI uses the tag as the release title by default.

​

8) Verify the published release

gh release view vX.Y.0 --web

• Confirm title, notes, and tag target are correct.
• Optional: if your repo uses release attestations, run gh release verify vX.Y.0.
• Confirm the release tag_name is exactly vX.Y.0.
• Confirm there is no duplicate bare-tag release such as X.Y.0.
• Confirm there is no GitHub Release entry for any patch tag in that release line.

​

8.1) Canonicalize accidental duplicate release entries

• Keep the canonical vX.Y.0 tag and GitHub Release.
• Remove patch-version GitHub Releases such as v0.39.1 or v0.46.1; patch versions are not published release lines in SI.
• Remove bare-tag GitHub Releases such as 0.50.0 when a canonical v0.50.0 release already exists.
• If both local and remote git tags exist for a non-canonical patch tag, delete both:

git tag -d vX.Y.Z
git push origin :refs/tags/vX.Y.Z

• Re-fetch tags after cleanup so local state matches the remote:

git fetch --tags --prune origin

​

9) Verify automated CLI release assets

• publishes npm package @aureuma/si (when NPM_TOKEN secret is configured)
• updates Homebrew tap formula in Aureuma/homebrew-si (when HOMEBREW_TAP_PUSH_TOKEN is configured, or by fallback to GH_PAT_AUREUMA when that token has tap push access)
• verifies release assets + package + Homebrew sync in a final gate job
• runs a macOS Homebrew smoke install lane through si build installer smoke-homebrew

• linux/amd64
• linux/arm64
• darwin/amd64
• darwin/arm64

• si_<version>_linux_amd64.tar.gz
• si_<version>_linux_arm64.tar.gz
• si_<version>_darwin_amd64.tar.gz
• si_<version>_darwin_arm64.tar.gz
• checksums.txt

gh run list --workflow "CLI Release Assets" --limit 1
gh release view vX.Y.0 --json assets --jq '.assets[].name'
corepack pnpm view @aureuma/si version

curl -fsSL https://raw.githubusercontent.com/Aureuma/homebrew-si/main/Formula/si.rb | grep -n 'version "'

• The workflow validates that the workspace Cargo.toml version matches the release tag.
• Release assets are built by explicit GitHub Actions target jobs for Linux AMD64, Linux ARM64, macOS AMD64, and macOS ARM64.
• si build self verify checks checksums, archive contents, and binary format before upload.
• A failed workflow means release notes/tag were published, but binary assets were not fully attached.
• npm verification now includes a real installed-launcher check against the published release assets, not just registry visibility.
• Use si build corepack pnpm publish --dry-run for local corepack pnpm publish rehearsal.
• Use si build pnpm vault for vault-backed publish (default key: NPM_GAT_AUREUMA_VANGUARDA).
• Use si build homebrew core --output packaging/homebrew-core/si.rb to refresh core-submission formula metadata.
• Those commands default to the canonical SI workspace version from root Cargo.toml; pass --version only when you intentionally need a detached version target.

​

10) Verify repo-boundary stability for Viva integrations

cd /home/<user>/Development/viva
cargo fmt --all --check
cargo test --locked --quiet
cd /home/<user>/Development/si
si viva config set --repo /home/<user>/Development/viva --build true
si viva -- version
si viva -- doctor

• Viva should follow the same release discipline: tag/version validation, asset verification, and CI green before publishing.
• Prefer orbit github release create Aureuma/viva ... for Viva releases so the GitHub release flow stays operationally consistent across the stack.

​

Tagging Rules

• Use annotated tags only for minor releases: git tag -a vX.Y.0 -m "vX.Y.0" <commit>.
• Tags should point at the release commit that includes the changelog update.
• Push tags explicitly: git push origin vX.Y.0.
• Tag names are canonical only in vX.Y.0 form.
• Do not create bare release tags such as 0.50.0.
• Do not create or keep patch-only release tags as part of the published release surface.

​

Release Notes Style

• Lead with 2–4 key changes.
• Balance Added/Changed/Fixed where possible.
• Keep tone concise and user-focused.