Skip to content

Home

Jump to bottom
Fumika Mochizuki edited this page Jul 27, 2026 · 13 revisions

Releasing BlueScript

This guide is for maintainers who cut a BlueScript release. Automation does most of the publishing; your job is to prepare versions, create the GitHub Release correctly, and merge the docs PR.

Two workflows run when a GitHub Release is published:

Workflow What it does
Release Components Uploads the microcontroller ZIP and publishes @bscript/lang, @bscript/notebook, and @bscript/cli to npm
Release Website Snapshots docs and opens a PR against main

After you merge that PR, Deploy website publishes the site to GitHub Pages.

Choose the release type

Type GitHub Release Tag example npm dist-tag Docs version
Stable Pre-release unchecked v2.1.0 latest 2.1.x
Pre-release (alpha / beta / rc) Pre-release checked v2.1.0-alpha.1 alpha (or beta, rc, …) 2.1.0-alpha.x

Rules enforced by CI:

  • A GitHub pre-release must use a semver prerelease segment (2.1.0-alpha.1). Plain 2.1.0 will fail.
  • A stable GitHub release must not use a prerelease version. Tagging v2.1.0-alpha.1 without the Pre-release checkbox will fail.
  • The prerelease identifier must not be numeric-only (2.1.0-1 is rejected; use 2.1.0-alpha.1).

Prerequisites

Before creating the release:

  1. All intended changes are on main (or on the commit you will tag).
  2. CI is green for that commit.
  3. You have permission to create GitHub Releases and merge PRs into main.
  4. npm Trusted Publishing is configured for @bscript/lang, @bscript/cli, and @bscript/notebook for workflow release-components.yml (no long-lived NPM_TOKEN is used).

Step 1 — Bump package versions

Update these so they all match the version you will tag (without the leading v):

File What to set
lang/package.json "version"
notebook/package.json "version"
cli/package.json "version"
cli/package.json "dependencies"."@bscript/lang" and "@bscript/notebook" — exact same version (no ^ / ~)

Example for 2.1.0-alpha.1:

// lang/package.json, notebook/package.json, cli/package.json
"version": "2.1.0-alpha.1"

// cli/package.json dependencies
"@bscript/lang": "2.1.0-alpha.1",
"@bscript/notebook": "2.1.0-alpha.1"

Commit and push to main (or to the branch you will tag from).

The release workflow verifies every workspace version and every @bscript/* dependency against the tag. A mismatch fails the job before publish.

Step 2 — Create the GitHub Release (and tag)

Create the tag on the Releases page — do not create it from the CLI.

  1. Confirm the release commit is on main (or the target branch) and has been pushed.
  2. Open GitHub → Releases → Draft a new release.
  3. Under Choose a tag, type the new tag (e.g. v2.1.0-alpha.1 or v2.1.0) and select Create new tag on publish.
  4. Under Target, select the branch or commit that contains the version bumps from Step 1 (usually main).
  5. Set the title (usually the same as the tag).
  6. Write release notes.
  7. Critical:
    • Pre-release → check Set as a pre-release
    • Stable → leave it unchecked (and do not mark as latest pre-release)
  8. Click Publish release.

Publishing the release creates the tag and starts both workflows.

Step 3 — Watch CI

Release Components

Two jobs run in parallel:

1. Microcontroller ZIP

  • Zips microcontroller/
  • Uploads release-microcontroller-<tag>.zip to the GitHub Release (overwrites if re-run)

2. npm publish (order: lang → notebook → cli)

  • Decides the npm dist-tag (latest or alpha / beta / …)
  • Verifies package versions
  • Builds workspaces
  • Publishes each package
    • If that exact version already exists on npm → skip
    • Any other failure → job fails (do not ignore a green job without checking logs)

Install commands users will use:

# Stable
npm install -g @bscript/cli

# Pre-release (example: alpha)
npm install -g @bscript/cli@alpha

Release Website

  • Checks out main
  • Derives the Docusaurus version:
    • Stable 2.1.0 → 2.1.x
    • Pre-release 2.1.0-alpha.1 → 2.1.0-alpha.x
  • On a stable release, removes superseded prerelease doc versions whose base version is ≤ the stable version (e.g. releasing 2.1.1 removes 2.1.0-alpha.x and 2.1.1-beta.x, but keeps 2.2.0-alpha.x)
  • Snapshots docs from the release tag (not whatever landed on main after the tag)
  • Opens a PR:
    • Branch: docs-version-<doc-version>
    • Base: main

The site is not updated until you merge this PR.

Step 4 — Merge the docs PR

  1. Review the PR (versioned docs / sidebars / versions.json).
  2. Merge into main.
  3. Confirm Deploy website succeeds and check the live docs.

Clone this wiki locally