Skip to content

Update release docs to match the automated publish pipeline #40

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
yavorpanayotov merged 1 commit into from
Jun 12, 2026
Merged

Update release docs to match the automated publish pipeline #40

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
21 changes: 10 additions & 11 deletions docs/releasing.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,41 +2,40 @@

Pushing a `v*` tag triggers the release workflow, which builds and publishes all artifacts: Rust binaries, VSIX, npm tarballs, LSP and tree-sitter outputs. Everything ships from a single tag.

After CI finishes, two steps need manual action: publishing to crates.io and updating the Homebrew formula. The release script handles the full sequence.
Publishing is fully automated: CI publishes the GitHub release, pushes the crates to crates.io (`publish-crates` job, via the `CARGO_REGISTRY_TOKEN` secret) and updates the Homebrew formula (`update-homebrew` job, via the `HOMEBREW_TAP_TOKEN` secret). No local crates.io login or tap checkout is needed.

## What goes where

| Artifact | Destination | Automated? |
|---|---|---|
| Rust CLI binaries (4 platforms) | GitHub release | CI |
| Rust crates (allium-parser, allium-cli) | crates.io | Release script |
| Rust CLI binaries (5 targets) | GitHub release | CI |
| Rust crates (allium-parser, allium-cli) | crates.io | CI |
| VSIX | GitHub release | CI |
| npm tarballs (allium-cli, allium-lsp, tree-sitter) | GitHub release | CI |
| Homebrew formula | homebrew-allium tap | Release script |
| Homebrew formula | homebrew-allium tap | CI |

## Running a release

```bash
./scripts/release.sh 3.1.0
```

This bumps versions, commits, tags, pushes, waits for CI, publishes to crates.io and updates the Homebrew tap. Pass `--dry-run` to preview each step without making changes.
This bumps versions, commits, tags, pushes, and watches CI through to completion; CI publishes everything, including crates.io and the Homebrew tap. Pass `--dry-run` to preview each step without making changes.

For major language version bumps, also follow the checklist in `docs/versioning.md`.

Requires `gh` (GitHub CLI), `cargo` logged in to crates.io, and the `homebrew-allium` tap repo as a sibling directory.
Requires `gh` (GitHub CLI) and `cargo` on the PATH.

## Manual steps (if not using the script)

1. Bump versions: `./scripts/version-bump.sh <version>`
2. Commit, tag and push: `git add -A && git commit -m "v<version>" && git tag v<version> && git push origin main --tags`
3. Wait for CI to build and attach release artifacts
4. Publish to crates.io: `cargo publish -p allium-parser && cargo publish -p allium-cli`
5. Update Homebrew formula: `./scripts/update-homebrew-formula.sh <version>`
6. Push the tap repo
3. Watch CI build, attach and publish everything

If the CI publish jobs fail, the fallbacks are `cargo publish -p allium-parser && cargo publish -p allium-cli` (needs a crates.io login) and `./scripts/update-homebrew-formula.sh <version>` plus a push of the `homebrew-allium` tap repo.

## When to release

All core-tier packages share a major.minor version (see `docs/versioning.md`). Right now, every release cuts a single tag and publishes everything. This means a tree-sitter bugfix produces new Rust binaries even if nothing changed in the Rust crates, and vice versa.

This is fine while the project is small. If the coupling becomes a problem, the natural split is separate tags per artifact group (e.g. `cli-v1.0.1`, `vscode-v0.3.0`), each triggering only its own CI job. That would also let the Homebrew update script run automatically as a post-release workflow step rather than requiring a manual invocation.
This is fine while the project is small. If the coupling becomes a problem, the natural split is separate tags per artifact group (e.g. `cli-v1.0.1`, `vscode-v0.3.0`), each triggering only its own CI job.
2 changes: 1 addition & 1 deletion docs/versioning.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -47,7 +47,7 @@ When the Allium language version changes (e.g. v2 → v3):
1. Run `scripts/version-bump.sh <new-version>` to update all manifests.
2. Update the language version statement at the top of this file.
3. Update the "Compatibility" line in each external editor plugin README.
4. After CI publishes the release, run `scripts/update-homebrew-formula.sh <version>` and push the tap repo. See `docs/releasing.md` for the full steps.
4. CI publishes the release, the crates and the Homebrew formula automatically. See `docs/releasing.md` for the full steps.

## Rules

Expand Down
Loading