Skip to content

release_process.md

Latest commit

 

History

History
391 lines (290 loc) · 18.5 KB

release_process.md

File metadata and controls

391 lines (290 loc) · 18.5 KB
Raw

Release Process Documentation

This file documents the current (and evolving) release process for KSON.

Release Preparation Process:

When main is ready to have a release cut from it:

  • Choose an appropriate X.Y.Z version number for the release by incrementing the latest tag (see existing tags here) according to Semantic Versioning guidelines
  • Create a branch release/X.Y.Z for this release
  • On main, bump our pinned dependencies according to the process in Regular Dependency Maintenance (this may be done in parallel to the release, or right after, but must not be neglected)

On the main branch:

  • Search the codebase for [[kson-version-num]] and update all version numbers to be snapshot/development versions for the next version. Generally this will bump to the next minor version after X.Y.Z, ie. X.(Y+1).0. Here is a hopefully complete checklist of the artifacts we version and publish (please improve if/when gaps are found!):
  • Update the kson and kson-sys Cargo.lock files: 
    cargo update --workspace --manifest-path lib-rust/kson-sys/Cargo.toml
cargo update --workspace --manifest-path lib-rust/kson/Cargo.toml
  • Run build and tests to ensure that uv.lock is updated and to ensure that tests pass: 
    (cd buildSrc && ./gradlew check)
./gradlew build
    In uv.lock, only the kson-lang version should change (delete lib-python/.uv/ and rebuild if revision also changes).
  • Manufacture a commit and pull request with these changes.

On the release/X.Y.Z branch:

  • Search the codebase for [[kson-version-num]] to find and update all the development/snapshot versions to the new X.Y.Z version. Here's a hopefully complete checklist of the artifacts we version and publish that should marked [[kson-version-num]]:
  • Commit and push the release/X.Y.Z branch
  • Pushing the branch runs CircleCI across ALL supported platforms (pull requests only run the linux build)
    • Fix any platform specific issues found
  • Create tag vX.Y.Z if/when CircleCI is green for all platforms
  • Publish the release according the Publishing process below

Publishing Process:

  • Prepare release notes based on the changes made in this release. Sample Github comparison URL to see this release's changes: https://github.com/kson-org/kson/compare/[tag of current version]...release/X.Y.Z

Release artifacts built by CircleCI

Each of these CI jobs stores the release artifacts it builds into release-artifacts/<destination> on its Artifacts tab:

CircleCI job Artifact destination Contents
build-linux-amd64 release-artifacts/linux-amd64 kson-lib-shared-amd64-linux.tar.gz, kson-cli-amd64-linux.tar.gz, each with its .sha256
build-linux-amd64 release-artifacts/portable vscode-kson-plugin.vsix, kson-language-*.zip, kson_org-kson-*.tgz, kson_org-monaco-editor-*.tgz, kson_lang-*.tar.gz, each with its .sha256
build-macos-arm64 release-artifacts/macos-arm64 kson-lib-shared-arm64-macos.tar.gz, kson-cli-arm64-macos.tar.gz, each with its .sha256
build-windows-amd64 release-artifacts/windows-amd64 kson-lib-shared-amd64-windows.tar.gz, kson-cli-amd64-windows.tar.gz, each with its .sha256
build-python-wheel-linux-amd64 release-artifacts/python-linux-amd64 kson_lang-*.whl
build-python-wheel-macos release-artifacts/python-macos-arm64 kson_lang-*.whl
build-python-wheel-windows release-artifacts/python-windows-amd64 kson_lang-*.whl

.circleci/download-release-artifacts.sh downloads every job's artifacts of a branch's latest run into release-artifacts/<destination>/ under the current directory and verifies each .sha256. It needs the CircleCI CLI (1.11 or newer), logged in with circleci auth login:

.circleci/download-release-artifacts.sh release/X.Y.Z

Take a release's artifacts from the CI run on its own release/X.Y.Z branch; other runs build development versions.

kson-lib Publishing Process

The project uses the Vanniktech Maven Publish plugin to publish to Maven Central Portal. This process publishes both:

  • org.kson:kson (public API from kson-lib)
  • org.kson:kson-internals (internal implementation from root build that is deployed with kson-lib)
Prerequisites

Ensure you have credentials for both of these in your ~/.gradle/gradle.properties file:

mavenCentralUsername=<your-username>
mavenCentralPassword=<your-password>

# GPG signing credentials
signing.keyId=<your-key-id>
signing.password=<your-passphrase>
signing.secretKeyRingFile=<path-to-secring.gpg>
Publishing Steps

  1. Ensure you've checked out the tag to be released and that git status is clean

  2. Publish to Maven Central:

    ./gradlew publishAllPublicationsToMavenCentralRepository -Prelease=true

  3. Verify the publications are valid and ready to be published: https://central.sonatype.com/publishing/deployments

  4. Manually release: we have automaticRelease = false as a final gate/protection, so once everything looks good at https://central.sonatype.com/publishing/deployments for this release, click Publish

lib-rust Publishing Process

Three artifacts, published in this order:

  1. kson-binaries release kson-lib-X.Y.Z — the prebuilt native libraries
  2. kson-sys on crates.io
  3. kson-rs on crates.io

Unless KSON_ROOT_SOURCE_DIR or KSON_PREBUILT_BIN_DIR is set, kson-sys's build script downloads its native library from:

https://github.com/kson-org/kson-binaries/releases/download/kson-lib-{KSON_LIB_VERSION}/kson-lib-shared-{arch}-{os}.tar.gz

cargo publish verifies by building, so step 1 must be complete before step 3.

Prerequisites
  • The tag to be released checked out, with git status clean. Steps 1, 2 and 3 all read versions from the working tree — KSON_LIB_VERSION and the crate versions — so running them from main or a feature branch publishes or verifies the wrong version.
  • A crates.io account, authenticated locally (cargo login), with publish rights on both kson-rs and kson-sys
  • Write access to https://github.com/kson-org/kson-binaries
  • The gh CLI, authenticated
  • Green build-linux and build-release-targets workflows on the release branch
Step 1: Cut the kson-binaries release

CI builds these archives under the names the download URL needs, so they need no repackaging. The three build-* jobs of this release's CI run store them under release-artifacts/<platform> (see Release artifacts built by CircleCI to download them):

CircleCI job Release asset
build-linux-amd64 kson-lib-shared-amd64-linux.tar.gz
build-macos-arm64 kson-lib-shared-arm64-macos.tar.gz
build-windows-amd64 kson-lib-shared-amd64-windows.tar.gz

Job names and artifact destinations have changed between releases. Confirm both against the release branch's .circleci/config.kson.

Only shared assets are needed. build.rs derives the asset name from the Rust target triple (aarch64 → arm64, x86_64 → amd64; OS is linux, macos, or windows). Consumers on a combination we do not ship must set KSON_ROOT_SOURCE_DIR or KSON_PREBUILT_BIN_DIR themselves.

  1. Confirm KSON_LIB_VERSION in build.rs matches the tag you are about to create. If they disagree, every downstream cargo build 404s.

  2. Sanity-check a tarball on your own platform before uploading:

    mkdir -p /tmp/kson-verify
tar -xzf release-artifacts/macos-arm64/kson-lib-shared-arm64-macos.tar.gz -C /tmp/kson-verify
env -u KSON_ROOT_SOURCE_DIR KSON_PREBUILT_BIN_DIR=/tmp/kson-verify \
    cargo build --manifest-path lib-rust/kson/Cargo.toml

    Each archive holds its platform's native-image output, the shared library and its headers, flat at the archive root. Every file in it is platform-specific, so never mix files between archives.

  3. Create the release and upload all three assets:

    gh release create kson-lib-X.Y.Z \
    --repo kson-org/kson-binaries \
    --title kson-lib-X.Y.Z \
    release-artifacts/linux-amd64/kson-lib-shared-amd64-linux.tar.gz \
    release-artifacts/windows-amd64/kson-lib-shared-amd64-windows.tar.gz \
    release-artifacts/macos-arm64/kson-lib-shared-arm64-macos.tar.gz
Step 2: Verify the download path

No CI job covers this path. With both env vars unset:

env -u KSON_ROOT_SOURCE_DIR -u KSON_PREBUILT_BIN_DIR \
    cargo build --manifest-path lib-rust/kson/Cargo.toml

A failure here means the kson-binaries release is missing, misnamed, or disagrees with KSON_LIB_VERSION. Fix it before continuing: published crates can only be yanked, never changed.

Step 3: Publish to crates.io

  1. Dry-run both crates:

    cargo publish --dry-run --manifest-path lib-rust/kson-sys/Cargo.toml
cargo publish --dry-run --manifest-path lib-rust/kson/Cargo.toml \
    --config 'patch.crates-io.kson-sys.path="lib-rust/kson-sys"'

  2. Publish kson-sys:

    cargo publish --manifest-path lib-rust/kson-sys/Cargo.toml

  3. Wait for the crates.io index to update (usually under a minute), then publish kson-rs:

    cargo publish --manifest-path lib-rust/kson/Cargo.toml
Step 4: Verify

Confirm the new version resolves from outside the repo:

cargo new /tmp/kson-smoke && cd /tmp/kson-smoke
cargo add kson-rs
cargo build

kson-lib npm package Publishing Process

The KSON JavaScript/TypeScript library is published to npm as @kson_org/kson with support for both browser and Node.js environments.

Prerequisites
  • You will need an npm account at https://www.npmjs.com/
  • You will need publish access to the @kson_org/kson package
Publishing Steps

  1. Take kson_org-kson-X.Y.Z.tgz from release-artifacts/portable/

  2. Publish to npm:

    npm login
npm publish release-artifacts/portable/kson_org-kson-X.Y.Z.tgz --access=public

  3. Verify the package is available at: https://www.npmjs.com/package/@kson_org/kson

lib-python Publishing Process

The Python package is published to PyPI as kson-lang using platform-specific wheels built by CircleCI.

Prerequisites
  • You will need a PyPI account at https://pypi.org/
  • You will need the PyPI API token (stored in MM 1Password)
Publishing Steps

  1. Ensure you've checked out the tag to be released and that git status is clean

  2. Copy kson_lang-X.Y.Z.tar.gz from release-artifacts/portable/ into the lib-python/dist/ directory

    This archive is source only: it carries no native library and cannot build one, so nobody installs from it. It puts the source on PyPI; every installable artifact is a wheel from step 3.

  3. Copy the pre-built wheels from release-artifacts/python-*/ (one per build-python-wheel-* job) into the lib-python/dist/ directory

  4. Upload to PyPI using twine:

    cd lib-python
./uvw run python -m twine upload --repository pypi dist/* --verbose
    • Use the API Token when prompted

  5. Verify the package is available at: https://pypi.org/project/kson-lang/

tooling/cli Publishing Process

Collecting the CLI binaries

The three build-* CircleCI jobs each build the kson native binary for their platform and store it as kson-cli-<arch>-<os>.tar.gz, holding kson, or kson.exe on Windows. Download all three from this release's CI run; see Release artifacts built by CircleCI.

  • todo doc where these binaries get published — no distribution channel has been chosen yet

tooling/lsp-clients Publishing Process

The KSON language support includes VSCode extensions published to both the Visual Studio Code Marketplace and Open VSX Registry.

Prerequisites
Publishing Steps

  1. Take vscode-kson-plugin.vsix from release-artifacts/portable/

  2. Publish to VS Code Marketplace:

  3. Publish to Open VSX Registry:

  4. Verify the extensions are available at:

tooling/lsp-clients/monaco Publishing Process

The Monaco editor integration is published to npm as @kson_org/monaco-editor.

Prerequisites
  • You will need a npm account at https://www.npmjs.com/
  • You will need publish access to the @kson_org organization
Publishing Steps

  1. Take kson_org-monaco-editor-X.Y.Z.tgz from release-artifacts/portable/

  2. Check what will be published:

    tar tzf release-artifacts/portable/kson_org-monaco-editor-X.Y.Z.tgz # should list package/dist/ and package/dist-iframe/
tar xzOf release-artifacts/portable/kson_org-monaco-editor-X.Y.Z.tgz package/package.json # should have no "dependencies", and "devDependencies" linking two other kson projects

    The bundle inlines @kson/lsp-shared and kson-language-server, which is why they are devDependencies: the published package resolves nothing at install time beyond its monaco-editor and react peers.

  3. Publish to npm:

    npm login
npm publish release-artifacts/portable/kson_org-monaco-editor-X.Y.Z.tgz --access=public

  4. Verify the package:

    npm view @kson_org/monaco-editor dist-tags

    latest should now be the released version. Development builds are published under the dev tag, so latest otherwise keeps pointing at whichever prerelease was published without a tag.

tooling/jetbrains Publishing Process

Note: it is possible to automate this process us some Gradle tasks provided by the IntelliJ Platform Gradle Plugin, if/when this manual process become onerous.

  1. Take kson-language-X.Y.Z.zip from release-artifacts/portable/

  2. Manually upload to JetBrains Marketplace: