v4.0.0b5

Releasing API updates is quite a long and error prone process, so the point that it was limiting our ability to push frequent updates in practice. There were 5 tag, commit, wait, and proceed steps and you'd have to start over or force push if a mistake was made.

This keeps all the npm packages as they were, but versions everything from a single source of truth, which is this project's main version. Everything builds on a tag on the main repo, much like we did for a regular IDE docs RTD release.

It also skips the PyPI for jedi as an intermediate step, which isn't really needed and required us to have this strict order of publication steps.

.github/workflows/build.yml

@@ -22,7 +22,7 @@ jobs:
 
     runs-on: ubuntu-22.04
     steps:
-    - uses: actions/checkout@v3
+    - uses: actions/checkout@v6
       with:
         submodules: recursive
     - name: Install dependencies

.github/workflows/jedi.yml

@@ -7,24 +7,9 @@ jobs:
     if: github.ref_type != 'tag'
     runs-on: ubuntu-22.04
     steps:
-    - uses: actions/checkout@v3
+    - uses: actions/checkout@v6
     - run: pipx install poetry
     - run: poetry install
       working-directory: ./jedi
     - run: poetry run pytest -vv
       working-directory: ./jedi
-
-  publish:
-    if: github.ref_type == 'tag' && startsWith(github.ref_name, 'pybricks_jedi/')
-    runs-on: ubuntu-22.04
-    steps:
-    - uses: actions/checkout@v3
-    - run: pipx install poetry
-    - run: poetry install
-      working-directory: ./jedi
-    - run: poetry build
-      working-directory: ./jedi
-    - run: poetry publish
-      working-directory: ./jedi
-      env:
-        POETRY_PYPI_TOKEN_PYPI: ${{ secrets.PYPI_PYBRICKS_JEDI_TOKEN }}

.github/workflows/publish-ide-docs.yml

@@ -2,22 +2,33 @@ name: Release @pybricks/ide-docs
 
 on:
   push:
-    tags: 
-    - '@pybricks/ide-docs/**'
+    tags:
+    - 'v4.*'
+
+permissions:
+  id-token: write
+  contents: read
 
 jobs:
   publish_ide_docs:
     runs-on: ubuntu-22.04
     steps:
+    - name: Get version from tag
+      run: |
+        VERSION="${GITHUB_REF_NAME#v}"
+        NPM_VERSION=$(echo "$VERSION" | sed 's/\([0-9]\)a\([0-9]\)/\1-alpha.\2/;s/\([0-9]\)b\([0-9]\)/\1-beta.\2/;s/\([0-9]\)rc\([0-9]\)/\1-rc.\2/')
+        echo "VERSION=$VERSION" >> $GITHUB_ENV
+        echo "NPM_VERSION=$NPM_VERSION" >> $GITHUB_ENV
+        echo "NPM_TAG=$(echo "$NPM_VERSION" | grep -q '-' && echo 'next' || echo 'latest')" >> $GITHUB_ENV
     - name: Ubuntu packages
       run: |
         sudo apt-get update
         sudo apt-get install -y dvisvgm preview-latex-style texlive texlive-fonts-extra texlive-latex-extra
-    - uses: actions/checkout@v3
+    - uses: actions/checkout@v6
       with:
         submodules: recursive
     - name: Set up Python 3.8
-      uses: actions/setup-python@v4
+      uses: actions/setup-python@v5
       with:
         python-version: 3.8
     - name: Install dependencies
@@ -26,13 +37,13 @@ jobs:
         poetry run python -m pip install --upgrade pip
         poetry run python -m pip install --upgrade setuptools
         poetry install --only=doc
-    - uses: actions/setup-node@v3
+    - uses: actions/setup-node@v4
       with:
-        node-version: '14.x'
+        node-version: '24'
         registry-url: 'https://registry.npmjs.org'
+    - run: npm version --no-git-tag-version "$NPM_VERSION"
+      working-directory: npm/ide-docs
     - run: yarn build
       working-directory: npm/ide-docs
-    - run: yarn publish
+    - run: npm publish --tag "$NPM_TAG"
       working-directory: npm/ide-docs
-      env:
-        NODE_AUTH_TOKEN: ${{ secrets.NODE_AUTH_TOKEN }}

.github/workflows/publish-images.yml

@@ -9,11 +9,11 @@ jobs:
   publish_ide_docs:
     runs-on: ubuntu-22.04
     steps:
-    - uses: actions/checkout@v3
+    - uses: actions/checkout@v6
     # Setup .npmrc file to publish to npm
-    - uses: actions/setup-node@v3
+    - uses: actions/setup-node@v4
       with:
-        node-version: '16.x'
+        node-version: '22.x'
         registry-url: 'https://registry.npmjs.org'
     - run: ./build.py
       working-directory: npm/images

.github/workflows/publish-jedi.yml

@@ -2,22 +2,39 @@ name: Release @pybricks/jedi
 
 on:
   push:
-    tags: 
-    - '@pybricks/jedi/**'
+    tags:
+    - 'v4.*'
+
+permissions:
+  id-token: write
+  contents: read
 
 jobs:
   publish_jedi:
     runs-on: ubuntu-22.04
     steps:
-    - uses: actions/checkout@v3
-    # Setup .npmrc file to publish to npm
-    - uses: actions/setup-node@v3
+    - uses: actions/checkout@v6
+    - name: Get version from tag
+      run: |
+        VERSION="${GITHUB_REF_NAME#v}"
+        NPM_VERSION=$(echo "$VERSION" | sed 's/\([0-9]\)a\([0-9]\)/\1-alpha.\2/;s/\([0-9]\)b\([0-9]\)/\1-beta.\2/;s/\([0-9]\)rc\([0-9]\)/\1-rc.\2/')
+        echo "VERSION=$VERSION" >> $GITHUB_ENV
+        echo "NPM_VERSION=$NPM_VERSION" >> $GITHUB_ENV
+        echo "NPM_TAG=$(echo "$NPM_VERSION" | grep -q '-' && echo 'next' || echo 'latest')" >> $GITHUB_ENV
+    - name: Set up Python
+      uses: actions/setup-python@v5
       with:
-        node-version: '16.x'
+        python-version: '3.11'
+    - name: Install poetry
+      run: pipx install poetry
+    - name: Set pybricks-jedi version
+      run: poetry version "$VERSION"
+      working-directory: jedi
+    - uses: actions/setup-node@v4
+      with:
+        node-version: '24'
         registry-url: 'https://registry.npmjs.org'
-    - run: ./build.py
+    - run: ./build.py "$NPM_VERSION"
       working-directory: npm/jedi
-    - run: yarn publish
+    - run: npm publish --tag "$NPM_TAG"
       working-directory: npm/jedi/build
-      env:
-        NODE_AUTH_TOKEN: ${{ secrets.NODE_AUTH_TOKEN }}

.github/workflows/release.yml

@@ -1,7 +1,7 @@
 on:
   push:
     tags:
-    - 'v3.*'
+    - 'v4.*'
 
 name: Create release on GitHub and PyPI
 
@@ -14,7 +14,7 @@ jobs:
     runs-on: ubuntu-22.04
     steps:
       - name: Checkout code
-        uses: actions/checkout@v3
+        uses: actions/checkout@v6
         with:
           submodules: true
           fetch-depth: 0
@@ -38,7 +38,7 @@ jobs:
   build_and_publish:
     runs-on: ubuntu-22.04
     steps:
-    - uses: actions/checkout@v3
+    - uses: actions/checkout@v6
     - run: pipx run poetry build
     - run: pipx run poetry publish
       env:

CHANGELOG.md

@@ -4,6 +4,38 @@
 
 ## Unreleased
 
+## 4.0.0b4 - 2026-05-29
+
+### Changed
+
+- Tag npm prereleases.
+
+## 4.0.0b4 - 2026-05-29
+
+### Changed
+
+- Bump node version.
+
+## 4.0.0b3 - 2026-05-29
+
+### Changed
+
+- Fixed NPM publishing permissions.
+
+## 4.0.0b2 - 2026-05-29
+
+### Changed
+
+- Change NPM publishing to trusted publishers.
+
+
+## 4.0.0b1 - 2026-05-29
+
+### Changed
+
+- Updated API for firmware 4.0.0bx. See upstream changelog for details.
+- Updated release pipeline to publish rtd, npm/docs and npm/jedi on tag.
+
 ### Fixed
 
 - Fixed `DriveBase.angle` reporting an incorrect return type.

CONTRIBUTING.md

@@ -163,6 +163,11 @@ Linting:
     poetry run flake8  # check Python
     poetry run doc8  # check Restructured Text
 
+Building all release artifacts (docs, jedi, npm packages):
+
+    # Linux/macOS only
+    ./build-all.sh
+
 [vscode]: https://code.visualstudio.com/
 [git]: https://git-scm.com/
 [python]: https://www.python.org/

build-all.sh

@@ -0,0 +1,47 @@
+#!/usr/bin/env bash
+# Build all release artifacts locally (equivalent to CI workflows, minus publish).
+set -euo pipefail
+
+REPO_ROOT="$(realpath "$(dirname "${BASH_SOURCE[0]}")")"
+
+# Activate the project venv so python/make/etc. all use it without poetry run
+source "$REPO_ROOT/.venv/bin/activate"
+
+# Read version from pyproject.toml
+VERSION=$(grep '^version = ' "$REPO_ROOT/pyproject.toml" | head -1 | sed 's/version = "\(.*\)"/\1/')
+# Convert Python pre-release format (e.g. 4.0.0a1, 4.0.0b1, 4.0.0rc1) to npm semver (e.g. 4.0.0-alpha.1, 4.0.0-beta.1, 4.0.0-rc.1)
+NPM_VERSION=$(echo "$VERSION" | sed 's/\([0-9]\)a\([0-9]\)/\1-alpha.\2/;s/\([0-9]\)b\([0-9]\)/\1-beta.\2/;s/\([0-9]\)rc\([0-9]\)/\1-rc.\2/')
+echo "==> Building version $VERSION (npm: $NPM_VERSION)"
+
+# lint
+echo "==> Linting"
+cd "$REPO_ROOT"
+flake8
+doc8
+
+# pybricks-jedi wheel (from local source)
+echo "==> Testing pybricks-jedi"
+cd "$REPO_ROOT/jedi"
+poetry run pytest -vv
+
+echo "==> Building pybricks-jedi wheel"
+cd "$REPO_ROOT/jedi"
+rm -rf dist/
+poetry build --format=wheel
+
+# @pybricks/jedi npm package
+echo "==> Building @pybricks/jedi"
+cd "$REPO_ROOT"
+python3 npm/jedi/build.py "$NPM_VERSION"
+
+# @pybricks/ide-docs npm package
+echo "==> Building @pybricks/ide-docs"
+cd "$REPO_ROOT"
+make -C doc clean
+cd "$REPO_ROOT/npm/ide-docs"
+yarn build
+
+echo ""
+echo "Build complete."
+echo "  jedi npm package : npm/jedi/build/"
+echo "  ide-docs         : npm/ide-docs/html/"

jedi/pyproject.toml

@@ -1,6 +1,7 @@
 [tool.poetry]
 name = "pybricks_jedi"
-version = "1.17.0"
+# Version is set automatically at build time from the root pyproject.toml. Do not edit.
+version = "0.0.0"
 description = "Code completion for Pybricks."
 authors = ["The Pybricks Authors <team@pybricks.com>"]
 license = "MIT"

npm/ide-docs/.yarnrc

@@ -1,2 +0,0 @@
-version-tag-prefix "@pybricks/ide-docs/v"
-version-git-message "@pybricks/ide-docs v%s"

npm/ide-docs/CHANGELOG.md

@@ -1,114 +0,0 @@
-# Changelog
-
-<!-- refer to https://keepachangelog.com/en/1.0.0/ for guidance -->
-
-## 2.20.0 - 2024-02-26
-
-### Changed
-- Updated docs to v3.6.0b5.
-
-## 2.19.0 - 2024-04-11
-
-### Changed
-- Updated docs to v3.5.0.
-
-## 2.18.0 - 2024-04-05
-
-### Changed
-- Updated docs to v3.5.0b2.
-
-## 2.17.0 - 2024-03-21
-
-### Changed
-- Updated docs to v3.5.0b1.
-
-## 2.16.0 - 2024-03-11
-
-### Changed
-- Updated docs to v3.4.0.
-
-## 2.15.0 - 2024-03-05
-
-### Changed
-- Updated docs to v3.4.0b5.
-
-## 2.14.0 - 2024-01-30
-
-### Changed
-- Updated docs to v3.4.0b3.
-
-## 2.13.0 - 2023-11-24
-
-### Changed
-- Updated docs to v3.4.0b1.
-
-## 2.12.0 - 2023-11-24
-
-### Changed
-- Updated docs to v3.3.0.
-
-## 2.11.0 - 2023-11-20
-
-### Changed
-- Updated docs to v3.3.0c1.
-
-## 2.10.0 - 2023-10-26
-
-### Changed
-- Updated docs to v3.3.0b9.
-
-## 2.9.0 - 2023-05-16
-
-### Changed
-- Updated docs to v3.3.0b5.
-
-## 2.8.0 - 2023-04-21
-
-### Changed
-- Updated docs to v3.3.0b4.
-
-## 2.7.0 - 2022-12-20
-
-### Changed
-- Updated docs to v3.2.0c2.
-
-## 2.6.0 - 2022-12-09
-
-### Changed
-- Updated docs to v3.2.0c1.
-
-## 2.5.0 - 2022-12-02
-
-### Changed
-- Updated docs to v3.2.0b6.
-
-## 2.4.0 - 2022-11-11
-
-### Changed
-- Updated docs to v3.2.0b5.
-
-## 2.3.0 - 2022-10-21
-
-### Changed
-- Updated docs to v3.2.0b4.
-
-## 2.2.0 - 2022-06-02
-
-### Changed
-- Updated docs to v3.2.0b1.
-
-## 2.1.0 - 2021-12-16
-
-### Changed
-- Updated docs to v3.1.0.
-
-## 2.0.1 - 2021-11-19
-
-### Fixed
-- Fixed link to Color Light Matrix page.
-
-## 2.0.0 - 2021-11-19
-
-### Changed
-- Changed package directory structure.
-- Updated docs to v3.1.0rc1.

npm/ide-docs/package.json

@@ -1,10 +1,10 @@
 {
   "name": "@pybricks/ide-docs",
-  "version": "2.20.0",
+  "version": "0.0.0",
   "description": "Special build of Pybricks API docs for embedding in an IDE.",
   "repository": {
     "type": "git",
-    "url": "https://github.com/pybricks/pybricks-api",
+    "url": "git+https://github.com/pybricks/pybricks-api.git",
     "directory": "npm/ide-docs"
   },
   "publishConfig": {

npm/images/build.py

@@ -18,7 +18,7 @@ package_json = {
     "license": "MIT",
     "repository": {
         "type": "git",
-        "url": "https://github.com/pybricks/pybricks-api",
+        "url": "git+https://github.com/pybricks/pybricks-api.git",
         "directory": "npm/images",
     },
     "publishConfig": {"registry": "https://registry.npmjs.org", "access": "public"},

npm/jedi/.yarnrc

@@ -1,2 +0,0 @@
-version-tag-prefix "@pybricks/jedi/v"
-version-git-message "@pybricks/jedi v%s"

npm/jedi/CHANGELOG.md

@@ -1,99 +0,0 @@
-# Changelog
-
-<!-- refer to https://keepachangelog.com/en/1.0.0/ for guidance -->
-
-## Unreleased
-
-## 1.17.0 - 2025-02-26
-
-### Changed
-- Updated `pybricks_jedi` Python package to v1.17.0.
-
-## 1.16.0 - 2024-04-05
-
-### Changed
-- Updated `pybricks_jedi` Python package to v1.16.0.
-
-## 1.15.0 - 2024-03-21
-
-### Changed
-- Updated `pybricks_jedi` Python package to v1.15.0.
-
-## 1.14.0 - 2024-03-05
-
-### Changed
-- Updated `pybricks_jedi` Python package to v1.14.0.
-
-## 1.13.0 - 2024-01-30
-
-### Changed
-- Updated `pybricks_jedi` Python package to v1.13.0.
-
-### Changed
-- Updated `pybricks_jedi` Python package to v1.12.0.
-
-## 1.12.0 - 2023-11-24
-
-### Changed
-- Updated `pybricks_jedi` Python package to v1.12.0.
-
-## 1.11.0 - 2023-11-20
-
-### Changed
-- Updated `pybricks_jedi` Python package to v1.11.0.
-
-## 1.10.0 - 2023-10-26
-
-### Changed
-- Updated `pybricks_jedi` Python package to v1.10.0.
-
-## 1.9.0 - 2023-05-16
-
-### Changed
-- Updated `pybricks_jedi` Python package to v1.9.0.
-
-## 1.8.0 - 2023-04-21
-
-### Changed
-- Updated `pybricks_jedi` Python package to v1.8.0.
-
-## 1.7.0 - 2022-12-28
-
-### Changed
-- Updated `pybricks_jedi` Python package to v1.7.0.
-
-## 1.6.0 - 2022-12-09
-
-### Changed
-- Updated `pybricks_jedi` Python package to v1.6.0.
-
-## 1.5.0 - 2022-12-02
-
-### Changed
-- Updated `pybricks_jedi` Python package to v1.5.0.
-
-## 1.4.0 - 2022-12-02
-
-### Changed
-- Updated `pybricks_jedi` Python package to v1.4.0.
-
-## 1.3.0 - 2022-11-11
-
-### Changed
-- Updated `pybricks_jedi` Python package to v1.3.0.
-
-## 1.2.0 - 2022-10-21
-
-### Changed
-- Updated `pybricks_jedi` Python package to v1.2.0.
-
-## 1.0.1 - 2022-09-07
-
-### Fixed
-- Fixed exports.
-- Fixed missing README and CHANGELOG.
-
-## 1.0.0 - 2022-09-07
-
-### Added
-- Added new @pybricks/jedi package.

npm/jedi/build.py

@@ -8,15 +8,23 @@ import subprocess
 import sys
 import zipfile
 
-BUILD_DIR = (pathlib.Path(__file__).parent / "build").resolve()
+if len(sys.argv) != 2:
+    print(f"Usage: {sys.argv[0]} <version>", file=sys.stderr)
+    sys.exit(1)
+
+VERSION = sys.argv[1]
+
+ROOT_DIR = pathlib.Path(__file__).parent.resolve()
+JEDI_SRC_DIR = (ROOT_DIR / ".." / ".." / "jedi").resolve()
+BUILD_DIR = (ROOT_DIR / "build").resolve()
 
 package_json = {
     "name": "@pybricks/jedi",
-    "version": "1.17.0",
+    "version": VERSION,
     "description": "Binary distribution of pybricks-jedi Python package and dependencies for use with Pyodide.",
     "repository": {
         "type": "git",
-        "url": "https://github.com/pybricks/pybricks-api",
+        "url": "git+https://github.com/pybricks/pybricks-api.git",
         "directory": "npm/jedi",
     },
     "publishConfig": {"registry": "https://registry.npmjs.org", "access": "public"},
@@ -30,7 +38,14 @@ whl_map: dict[str, str] = {}
 shutil.rmtree(BUILD_DIR, True)
 BUILD_DIR.mkdir()
 
-# download package and dependencies (*.whl files)
+# build pybricks-jedi wheel from local source
+subprocess.check_call(["poetry", "build", "--format=wheel"], cwd=JEDI_SRC_DIR)
+
+# copy locally built wheel to build dir
+for whl in (JEDI_SRC_DIR / "dist").glob("pybricks_jedi-*.whl"):
+    shutil.copy(whl, BUILD_DIR)
+
+# download transitive dependencies from PyPI, using the local wheel to satisfy pybricks-jedi itself
 subprocess.check_call(
     [
         sys.executable,
@@ -38,7 +53,8 @@ subprocess.check_call(
         "pip",
         "download",
         "--only-binary=any",
-        "pybricks-jedi==1.17.0",
+        f"--find-links={BUILD_DIR}",
+        "pybricks-jedi",
     ],
     cwd=BUILD_DIR,
 )
@@ -79,13 +95,8 @@ for whl in BUILD_DIR.glob("*.whl"):
 
             license_identifiers.add(license)
 
-        # TODO: The LICENSE workaround for the pybricks-jedi package can be
-        # dropped after the next release of that package
         if whl.name.startswith("pybricks_jedi-"):
-            LICENSE = (
-                pathlib.Path(__file__).parent.parent.parent / "jedi" / "LICENSE"
-            ).resolve()
-            with open(LICENSE) as lf:
+            with open(JEDI_SRC_DIR / "LICENSE") as lf:
                 license_text[whl.name] = lf.read()
         else:
             try:
@@ -126,7 +137,5 @@ with open(BUILD_DIR / "LICENSE", "w") as f:
 
 # copy additional files
 
-ROOT_DIR = (pathlib.Path(__file__).parent).resolve()
-
-for file in "README.md", "CHANGELOG.md":
+for file in ("README.md",):
     shutil.copy(ROOT_DIR / file, BUILD_DIR / file)

pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "pybricks"
-version = "3.6.1"
+version = "4.0.0b5"
 description = "Documentation and user-API stubs for Pybricks MicroPython"
 authors = ["The Pybricks Authors <team@pybricks.com>"]
 maintainers = ["Laurens Valk <laurens@pybricks.com>", "David Lechner <david@pybricks.com>" ]