Releases - quantified-uncertainty/squiggle GitHub Wiki

Releases are automated with a custom GitHub Action: Release.

Release PR

When you run the Release action, it will do one of the following:

  1. If there are new changesets on main: open a "New Release" PR
  2. If there are new changesets on main, and the "New Release" PR already exists: Update the PR
  3. If there are no new changesets on main (i.e. immediately after the "New Release" PR is merged):
  • NPM packages will be published to NPM
  • vscode-squiggle extension will be published to VS Code marketplace
  • also, Changelog on the website will be updated
  • Git tags for all releases will be created
  • GitHub releases will be created for each published package
  • Then, the new PR for the next iteration will be opened (see below)

Post-release PR

Post-release PR is powered by pnpm post-publish script at the root of the repo, which calls ops/src/scripts/post-publish.ts.

post-publish script will generate a few configuration and source changes that you should merge back to main.

Here's what should be included in that PR:

  • bumps to x.y.(z+1)-0 versions for all main Squiggle packages (squiggle-lang, components, and others)
  • a new empty changeset file, so that the following Release action invocations don't do another release immediately
  • update to System.version constant in squiggle-lang
  • updates to versioned-playground:
    • install new dependency on newly released @quri/squiggle-components there
    • make it a default version
    • list it in lazily loaded React imports

Some of these changes are regex-based and can be fragile, which is one of the reasons why the post-release PR is not merged automatically to main. You should review it before merging.

Recommended Flow

For now, Release action should be invoked manually: go to https://github.com/quantified-uncertainty/squiggle/actions/workflows/release.yml and click "Run workflow". We will start invoking it automatically on every commit to main, eventually.

  1. Run Release action when you want to do a new release
  2. Review the PR, especially the generated website changelog and updated versions
  3. If any changelog files are messy, update files in .changeset until things are satisfactory; push to main directly and re-run the action to update the PR
  • alternatively, you can just update the generated CHANGELOG.md files in the PR and push to it
  1. If everything is ok, merge the PR.
  2. Run Release action again; check the logs to make sure that all packages were published and GitHub releases were updated.
  • if publishing has failed, fix it and try it again. (The action has to finish correctly, otherwise its output won't be committed back to the repo.)
  1. Check the newly opened post-release PR, review it and merge it too.
  2. Update Squiggle versions on Squiggle Hub in the database.
  3. Announce on EA Forecasting Slack, Squiggle Discord and QURI Medley newsletter

Recovering from broken published releases

If you've accidentally published a version that doesn't work, you'll have to publish a new patch version (e.g. if 0.9.1 is broken, publish 0.9.2).

You'll probably need to run changeset-version script locally and do a few patches by hand; our GitHub Action flow doesn't automate the recovery process.

Cleanup before publishing the fixed release:

  • remove the broken version from versioned-components/ dependencies and code
  • merge changes in CHANGELOG.md files and and vX.Y.Z.mdx file in website documentation:
    • replace the version in *.md
    • rename the mdx file in website changelogs
    • also don't forget to rename the reference to vX.Y.Z.mdx file in _meta.json

Cleanup after the fixed release:

  • deprecate the packages for the broken release from NPM (pnpm deprecate @quri/[email protected], repeat for all packages in fixed list from .changeset/config.json)
    • you can pnpm unpublish @quri/squiggle-components instead of deprecating, but for all other packages NPM won't allow unpublish because of dependents check; see npm docs for more
  • merge Github Releases notes manually
  • Note: it's not possible to unpublish a specific VS Code extension