A monorepo containing jupyter-blocks and jupyter-tidyblocks. Blockly extension for JupyterLab.
Update docs: add Phase 8 (CI/CD) and work summary section 16
- modernization-plan.md: fix version to 0.1.0, add Phase 8 documenting
publish-dev.yml, workflow fixes, bump-version.py changes, and version bump
- work-summary.md: add section 16 summarizing all CI/CD infrastructure work
from this session
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
+95
-1
+48
-1
docs/modernization-plan.md
+48
-1
docs/modernization-plan.md
···
7
7
8
8
**Base project:** jupyterlab-blockly v0.3.3 (forked from QuantStack/jupyterlab-blockly)
9
9
**Current name:** jupyter-blocks / jupyter-tidyblocks
10
-
**Current version:** 0.1.0-alpha.0
10
+
**Current version:** 0.1.0
11
11
12
12
---
13
13
···
307
307
| `packages/tidyblocks` | **Vite** library mode | ✅ |
308
308
| `packages/tidyblocks-extension` | **`@jupyterlab/builder ^4.5`** via `build-labextension` | ✅ |
309
309
| Monorepo orchestration | **Turborepo** | ✅ |
310
+
311
+
---
312
+
313
+
## Phase 8 — CI/CD & Release Infrastructure ✅
314
+
315
+
**Status: Complete**
316
+
317
+
### Dev publishing to TestPyPI
318
+
319
+
- ✅ Created `.github/workflows/publish-dev.yml`
320
+
- Triggers on push to `main` or manual dispatch
321
+
- Uses OIDC trusted publisher (no token secrets) with a `testpypi` environment
322
+
- Sets a dev version (`0.1.0-dev.{run_number}`) in all `package.json` files before building
323
+
- Copies `package.json` into each Python package directory (replacing symlinks via `rm -f` + `cp`) so `hatch-nodejs-version` resolves the file inside the build temp dir
324
+
- Builds both `jupyter_blocks` and `jupyter_tidyblocks` wheels with `python -m build --wheel`
325
+
- Publishes both to TestPyPI with `skip-existing: true`
326
+
327
+
> **One-time setup required:** Two pending trusted publishers must be configured on [test.pypi.org](https://test.pypi.org) — one for `jupyter-blocks` and one for `jupyter-tidyblocks` — pointing at the `publish-dev.yml` workflow with environment `testpypi`.
328
+
329
+
### Workflow fixes
330
+
331
+
- ✅ Replaced `jupyterlab/maintainer-tools/.github/actions/base-setup@v1` with explicit `setup-python@v5` + `setup-node@v4` in all workflows (base-setup is yarn/jlpm-only and conflicts with `packageManager: npm`)
332
+
- ✅ Upgraded all `actions/checkout@v3` → `v4`, `upload-artifact@v3` → `v4`
333
+
- ✅ Fixed `check-release.yml`: artifact name `jupyterlab_blockly-releaser-dist-*` → `jupyter-blocks-releaser-dist-*`; added `steps_to_skip: "build-python,check-python"` (jupyter_releaser's Python build is incompatible with a monorepo with two Python packages in subdirectories)
334
+
335
+
### Root pyproject.toml
336
+
337
+
- ✅ Added `python_package = "jupyter_blocks"` so `jupyter_releaser` build steps target the correct subdirectory instead of the repo root (which has no `[build-system]`)
338
+
- ✅ Moved `npm install` from `before-bump-version` hook to `before-build-npm` only (avoids dirtying `package-lock.json` before `bump-version.py`'s clean-state check runs)
339
+
340
+
### bump-version.py
341
+
342
+
- ✅ Reads current version directly from `packages/blocks-extension/package.json` instead of `jupyter_releaser.util.get_version()`, which was incorrectly returning `0.0.0` from the root `setup.py` shim
343
+
- ✅ Uses regex to convert JS semver pre-release notation (`-alpha.N`, `-beta.N`, `-rc.N`) to PEP 440 (`aN`, `bN`, `rcN`) for `packaging.version.Version` parsing
344
+
- ✅ Uses `ensure_ascii=False` in `json.dump` to preserve literal Unicode characters (e.g. em dashes) in package.json files
345
+
346
+
### Workspace dependency pinning
347
+
348
+
- ✅ All internal workspace dependencies changed from `"^0.1.0-alpha.0"` to `"*"` — prevents workspace link breakage when `bump-version.py` changes the version
349
+
350
+
### Version
351
+
352
+
- ✅ All packages bumped from `0.1.0-alpha.0` → `0.1.0`
353
+
354
+
### Local build script
355
+
356
+
- ✅ Created `scripts/build-local.sh` mirroring the `publish-dev.yml` steps for local iteration without CI
310
357
311
358
---
312
359
+47
docs/work-summary.md
+47
docs/work-summary.md
···
346
346
347
347
---
348
348
349
+
## 16. CI/CD & Release Infrastructure
350
+
351
+
**Motivation:** The project had no automated publishing pipeline and several
352
+
CI workflows were broken after the monorepo restructure.
353
+
354
+
### publish-dev.yml — dev builds to TestPyPI
355
+
356
+
Created `.github/workflows/publish-dev.yml` to publish pre-release dev builds
357
+
automatically on every push to `main`. Key design decisions:
358
+
359
+
- **OIDC trusted publisher** (no token secrets): the workflow uses
360
+
`id-token: write` permission and `pypa/gh-action-pypi-publish@release/v1`
361
+
with a `testpypi` environment. The project owner must configure two pending
362
+
trusted publishers on test.pypi.org (for `jupyter-blocks` and
363
+
`jupyter-tidyblocks`).
364
+
- **Dev version injection**: a Python snippet strips the pre-release label from
365
+
the current JS version and appends `-dev.{run_number}` before building, so
366
+
published packages have PEP 440-valid versions like `0.1.0.dev42`.
367
+
- **Symlink replacement**: `package.json` files in `jupyter_blocks/` and
368
+
`jupyter_tidyblocks/` are git-tracked symlinks (needed for
369
+
`hatch-nodejs-version` locally). In CI they are replaced with `rm -f` + `cp`
370
+
so the version-patched content is used and symlink resolution doesn't fail
371
+
inside the `pipx build` temp directory.
372
+
- **`--wheel` flag**: `python -m build --wheel` bypasses the sdist-then-wheel
373
+
flow, avoiding all symlink-in-sdist issues entirely.
374
+
375
+
### Workflow and config fixes
376
+
377
+
| Issue | Fix |
378
+
|---|---|
379
+
| `base-setup` action incompatible with npm | Replaced with `setup-python@v5` + `setup-node@v4` in all workflows |
380
+
| `actions/upload-artifact@v3` / `checkout@v3` deprecated | Upgraded to `@v4` across all workflows |
381
+
| `check-release.yml` artifact name | `jupyterlab_blockly-releaser-dist-*` → `jupyter-blocks-releaser-dist-*` |
382
+
| `jupyter_releaser` trying to build Python from repo root | Added `steps_to_skip: "build-python,check-python"` in `check-release.yml` |
383
+
| `jupyter_releaser` root build targeting wrong dir | Added `python_package = "jupyter_blocks"` to root `pyproject.toml` |
384
+
| `npm install` in `before-bump-version` dirtying `package-lock.json` | Moved to `before-build-npm` only |
385
+
| `get_version()` returning `0.0.0` | `bump-version.py` now reads directly from `packages/blocks-extension/package.json` |
386
+
| `json.dump` escaping em dashes as `\u2014` | Added `ensure_ascii=False` to all `json.dump` calls |
387
+
| Internal workspace deps breaking after version bump | Changed `"^0.1.0-alpha.0"` → `"*"` for all intra-monorepo deps |
388
+
389
+
### Version bump: 0.1.0-alpha.0 → 0.1.0
390
+
391
+
All packages bumped to the first stable release version. Dev suffix is
392
+
appended only during CI builds for TestPyPI.
393
+
394
+
---
395
+
349
396
## 15. Deferred / Future Work
350
397
351
398
The following features from the original