​

Releasing and Changelog Guide

​

Versioning Rules

• Use SemVer: MAJOR.MINOR.PATCH (tag format: vX.Y.Z).
• Breaking changes:
  • While the project is on the v0.x line: bump MINOR.
  • After the project graduates off the v0.x line: bump MAJOR.
• Features: bump MINOR.
• Fixes/docs-only releases: bump PATCH.

​

Changelog Format (Predefined)

## [vX.Y.Z] - 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 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.

​

1) Determine the next version + release name

• Decide vX.Y.Z using the SemVer rules above.
• Choose a short suggested name for the release title (e.g., “Safari Login Flow”).
• Title format for GitHub Release: vX.Y.Z - 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.

​

3) Bump version strings in code

• root Cargo.toml workspace.package.version

​

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-rs-cli -- build installer smoke-host
cargo run --quiet --locked -p si-rs-cli -- build installer smoke-npm
cargo run --quiet --locked -p si-rs-cli -- build installer smoke-homebrew
cargo run --quiet --locked -p si-rs-cli -- build installer smoke-docker
./.artifacts/cargo-target/release/si-rs build self assets --version vX.Y.Z --out-dir .artifacts/release-preflight
./.artifacts/cargo-target/release/si-rs build self verify --version vX.Y.Z --out-dir .artifacts/release-preflight
git add CHANGELOG.md Cargo.toml
git commit -m "Bump version to vX.Y.Z"

• Keep release prep changes in a dedicated commit.
• The release-assets preflight confirms archive packaging before publishing a GitHub Release.
• Include the npm 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.Z -m "vX.Y.Z"

• Annotated tags are recommended for releases and are the best practice (they store metadata like tagger, date, and message).

​

6) Push commits and the new tag

git push
git push origin vX.Y.Z

• 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.
• si 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.Z section into release-notes.md (manual or script).
2. Create the release with a title and notes file:

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

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

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

4. Equivalent gh fallback:

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

gh release create vX.Y.Z \\
  --title "vX.Y.Z - 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.Z \\
  --title "vX.Y.Z - Suggested Name" \\
  --generate-notes \\
  --notes-start-tag vA.B.C \\
  --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.C 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.

​

8) Verify the published release

gh release view vX.Y.Z --web

• Confirm title, notes, and tag target are correct.
• Optional: if your repo uses release attestations, run gh release verify vX.Y.Z.

​

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 + npm + Homebrew sync in a final gate job
• runs a macOS Homebrew smoke install lane through si build installer smoke-homebrew

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

• si_<version>_linux_amd64.tar.gz
• si_<version>_linux_arm64.tar.gz
• si_<version>_linux_armv7.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.Z --json assets --jq '.assets[].name'
npm 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.
• The workflow uses si build self assets as the single build path and si build self verify as the local archive verification path 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 npm publish --version vX.Y.Z --dry-run for local npm publish rehearsal.
• Use si build npm vault --version vX.Y.Z for vault-backed publish (default key: NPM_GAT_AUREUMA_VANGUARDA).
• Use si build homebrew core --version vX.Y.Z --output packaging/homebrew-core/si.rb to refresh core-submission formula metadata.

​

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 si 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: git tag -a vX.Y.Z -m "vX.Y.Z" <commit>.
• Tags should point at the release commit that includes the changelog update.
• Push tags explicitly: git push origin vX.Y.Z.

​

Release Notes Style

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