Skip to content

RELEASING.md

Latest commit

 

History

History
117 lines (89 loc) · 4.55 KB

RELEASING.md

File metadata and controls

117 lines (89 loc) · 4.55 KB
Raw

Releasing

A release spans three repositories, in this order:

  1. scratch-for-java (this repo) — Maven Central + a GitHub release with the fat jar, the NRW jar and the catalogs zip.
  2. online-ide — the browser runtime, published as an embedded build to https://cdn.openpatch.org/onlineide/<tag>/.
  3. hyperbook — pins the online-ide tag in packages/markdown/ide-releases.json and is published to npm.

The docs site (scratch4j.openpatch.org) builds with hyperbook@latest, so it picks up the new IDE the next time the Documentation workflow runs.

Steps 2 and 3 do not depend on step 1 being on Maven Central: the browser runtime is synced from the release branch, not from Central. Do them before merging the release PR, so the docs deploy that follows the merge already uses the new IDE. (If the release PR is merged first, re-run the Documentation workflow from the Actions tab — it has a workflow_dispatch trigger.)

1. Prepare the changeset

  • Add .changeset/<name>.md with frontmatter type: patch|minor|major. Only changes that reach the user get a changeset; documentation, tests, examples, tooling and CI changes get none.
  • The version in the poms is owned by the Version Bump workflow — never edit it by hand. The Check Version workflow fails on a pom/changelog mismatch.
  • Never mvn install on a release branch: the poms still carry the released version, and an install would overwrite it in ~/.m2 for every other project on the machine (Studio). Build inside the reactor (mvn package -pl <module> -am).

2. Merge to main

Push or merge to main with the changeset. The Version Bump workflow bumps every module in lockstep, regenerates the compatibility artifacts and catalogs (compatibility/browser-policy.json included), and opens the "Release vX.Y.Z" PR.

3. Synchronize online-ide

From the release branch:

scripts/sync-online-ide.sh /path/to/online-ide

The script runs scripts/reference-docs.sh, writes the compatibility contract, the catalogs, the probes and the assets into the online-ide checkout, and then verifies with --check that everything is current. Commit and push the changes in online-ide, then run its tests:

cd /path/to/online-ide
npm ci
npm run test:ci
npm run browser:install -- --with-deps
npm run test:browser

CI re-runs these checks on every push to main and in the release PR's validation, so a stale online-ide checkout fails the release.

4. Release online-ide

The embedded build publishes itself when a GitHub release is created. Tag main with the package version and the next -hyperbook.<build> number, then create the release:

cd /path/to/online-ide
version=$(node -p "require('./package.json').version")
build=$(( $(git ls-remote --tags origin 'v*-hyperbook.*' | grep -o 'hyperbook\.[0-9]*' | sort -t. -k2 -n | tail -1 | cut -d. -f2) + 1 ))
tag="v$version-hyperbook.$build"
git tag "$tag" && git push origin "$tag"
gh release create "$tag" --notes "Embedded build for Hyperbook: <what changed>"

The Release Embedded Build workflow builds dist-embedded.zip, attaches it to the release, and publishes it to https://cdn.openpatch.org/onlineide/$tag/ (see online-ide's docs/cdn-releases.md). The playground deploys itself on push to main.

5. Point hyperbook at the new build

In the hyperbook repo:

  1. packages/markdown/ide-releases.json: set "onlineide" to the new tag. The tests read the pin from this file, so there is no second place to update.

  2. Add .changeset/online-ide-build-<n>.md:

    ---
"@hyperbook/markdown": patch
"hyperbook": patch
---

Update the Online IDE runtime to build <n>: <what changed>.

  3. Push to main; the changesets workflow opens the Version Packages PR. Merge it to publish to npm.

6. Merge the release PR

Merge "Release vX.Y.Z" on this repo. The Release workflow deploys to Maven Central, builds the fat jar, the NRW jar and the catalogs zip, and creates the GitHub release. The same push runs the Documentation workflow, which builds the docs with the newest Hyperbook and deploys them to GitHub Pages — consistent with the new IDE if steps 4–5 are done. Otherwise re-run it from the Actions tab.

Afterwards

  • Verify scratch4j.openpatch.org: an interactive example compiles and runs against the new runtime.
  • The browser policy (compatibility/browser-policy.json) was regenerated by the Version Bump workflow; review it in the release PR.
  • online-ide-nrw is a separate fork. If the NRW IDE should follow a release, sync it the same way (step 3) and release it separately.