Releasing¶
Changelogs¶
stone’s changes go in CHANGELOG.md, and the VS Code extension’s and stone-lsp’s in
editors/vscode/CHANGELOG.md. Add each change under ## [Unreleased] when it lands, in an
### Added, ### Changed, ### Removed, or ### Fixed subsection.
Versions are bumped right after a release, so the version in Cargo.toml or package.json is
always the next one to release, and [Unreleased] holds its changes. Each release workflow
publishes a version’s section, or [Unreleased] if it has none yet, as the release notes, and
fails before building if both are empty. The bump after a release then renames [Unreleased]
to ## [X.Y.Z] - YYYY-MM-DD, dated with the tag’s day, and opens a new empty one above it. It
only does that when the current version’s tag exists, so bumping twice before a release leaves
the changelog alone.
scripts/changelog.sh does the work, and sh scripts/test-changelog.sh tests it and checks that
both changelogs are well formed and have notes for every release tag:
sh scripts/changelog.sh notes CHANGELOG.md 0.1.2 # prints 0.1.2's dated notes
sh scripts/changelog.sh release-notes CHANGELOG.md 0.1.3 # what the release workflow publishes
sh scripts/changelog.sh release CHANGELOG.md 0.1.3 # what the bump after it runs
stone¶
Check that
[Unreleased]inCHANGELOG.mdlists the release’s changes, and thatCargo.tomlhas its version.Tag the release and push the tag:
git tag v<version> && git push origin v<version>
Bump to the next version, which edits
Cargo.tomland stone’s entry in eachCargo.lock, and dates the release’s notes inCHANGELOG.md. Then commit it, as the script prints:sh scripts/bump-version.sh stone patch # or minor, major, or a version such as 1.0.0 git add Cargo.toml Cargo.lock fuzz/Cargo.lock bench/Cargo.lock CHANGELOG.md git commit -m "bump stone to 0.1.4" && git push origin HEAD
.github/workflows/release.yml checks that the tag matches Cargo.toml, builds stone with the
self-update and fetch features for x86-64 and arm64 Linux (musl) and macOS and for x86-64
Windows, smoke-tests each binary it can run, and publishes stone-<target>.tar.gz, or
stone-x86_64-windows.zip for Windows, plus a .sha256 for each as a GitHub release, with
the version’s section of CHANGELOG.md as its notes. It is always marked Latest.
Running the workflow by hand from the Actions tab builds and tests the archives without
publishing.
install.sh, install.ps1, and stone update all download from these releases. To test the install
script against a local release, build first and run
cargo build
sh scripts/test-install.sh
which serves a fake release from a file:// URL through STONE_DOWNLOAD_URL.
The VS Code extension¶
The same steps, with editors/vscode/CHANGELOG.md and editors/vscode/package.json:
Tag the release and push the tag:
git tag vscode-v<version> && git push origin vscode-v<version>
Bump to the next version, which edits
editors/vscode/package.jsonandpackage-lock.jsonand dates the release’s notes ineditors/vscode/CHANGELOG.md. The extension shipsstone-lsp, so this also setslsp/Cargo.tomland itsCargo.lockentry to the same version. Commit what the script prints:sh scripts/bump-version.sh vscode patch # or minor, major, or a version such as 1.0.0
.github/workflows/vscode.yml builds stone-lsp for each platform, packages a .vsix per
platform plus a universal one, and publishes them to the VS Code Marketplace and Open VSX, which
show editors/vscode/CHANGELOG.md on their Changelog tabs (the packaged copy has the tag’s
notes under the version’s heading, dated that day). Then it creates a GitHub release
titled “VS Code extension X.Y.Z” with every .vsix attached and the version’s section of the
changelog as its notes. That release is never marked Latest, since install.sh,
install.ps1, and stone update download from the Latest release.
Publishing needs the repository secret OVSX_PAT for Open VSX, and AZURE_CLIENT_ID and
AZURE_TENANT_ID for a Microsoft Entra ID app that is a member of the tarolling Marketplace
publisher.
The documentation¶
.github/workflows/docs.yml publishes this site to GitHub Pages on every push to main that
changes the docs, and builds it without publishing on pull requests.