use changesets (#3070)

boneskull · web-flow · commit b41c0809e25f · 2026-02-11T14:48:48.000-08:00
## Overview **This PR adopts [Changesets](https://github.com/changesets/changesets) for versioning and releasing.** Changesets are a solution to the problem of versioning and updating release notes. Unlike other solutions which generate release notes from [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/), Changesets do not prescribe a commit message format and provide more granular control over the contents of release notes. Instead, it keeps information about versions and release notes in a temporary file-based "database". These files are committed to version control, then "flushed" upon release. ### Adding Changesets To add a Changeset to your PR, you'll interface with [`@changesets/cli`](https://npm.im/@changesets/cli), which will ask you to choose whether the Changeset represents a patch, minor, or major version bump. It will also ask you to provide a changelog entry. That entry replaces our current convention for updating a `NEWS.md` file. Once complete, you'll be reminded to commit the Changeset (which will be a unique `.md` file in `.changeset/`), which you'll then push up to your PR. > [!NOTE] > > - Changesets don't need their own commit. > - Not all PRs need changesets--only those which impact the end user. > - [`changeset-bot`](https://github.com/changesets/bot) will automatically detect Changesets (or the lack thereof) and comment on any PR containing them with info about the version bump and the contents of the Changelog entry. ### Releasing The [Changesets Release Action](https://github.com/changesets/action) runs after every push to `master`. It creates and maintains a PR which uses the Changeset files it finds to bump packages and update `CHANGELOG.md` files. Once merged, this PR will create appropriate tags for all updated packages & GitHub Releases for each tag. ### Publishing To publish to npm, a maintainer will pull down the changes, then publish via `lerna publish from-package` (or `yarn npm:publish`)
diff --git a/.changeset/README.md b/.changeset/README.md
@@ -0,0 +1,8 @@
+# Changesets
+
+Hello and welcome! This folder has been automatically generated by `@changesets/cli`, a build tool that works
+with multi-package repos, or single-package repos to help you version and publish your code. You can
+find the full documentation for it [in our repository](https://github.com/changesets/changesets)
+
+We have a quick list of common questions to get you started engaging with this project in
+[our documentation](https://github.com/changesets/changesets/blob/main/docs/common-questions.md)
diff --git a/.changeset/config.json b/.changeset/config.json
@@ -0,0 +1,21 @@
+{
+  "$schema": "https://unpkg.com/@changesets/config@3.1.2/schema.json",
+  "access": "public",
+  "baseBranch": "master",
+  "bumpVersionsWithWorkspaceProtocolOnly": true,
+  "changelog": [
+    "@changesets/changelog-github",
+    {
+      "repo": "endojs/endo"
+    }
+  ],
+  "commit": false,
+  "fixed": [],
+  "ignore": [],
+  "linked": [],
+  "privatePackages": {
+    "tag": true,
+    "version": true
+  },
+  "updateInternalDependencies": "patch"
+}
diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
@@ -0,0 +1,37 @@
+name: Release
+
+on:
+  push:
+    branches:
+      - master
+
+concurrency: ${{ github.workflow }}-${{ github.ref }}
+
+permissions:
+  contents: write
+  pull-requests: write
+
+jobs:
+  release:
+    name: Release
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout Repo
+        uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
+
+        # without this, setup-node errors on mismatched yarn versions
+      - run: corepack enable
+
+      - name: Setup Node.js 20
+        uses: actions/setup-node@6044e13b5dc448c55e2357c09f80417699197238 # v6
+        with:
+          node-version: 22.x
+          cache: yarn
+
+      - name: Install Dependencies
+        run: yarn
+
+      - name: Process Changesets
+        # This action will create/update Changesets' Release PR *or* create a
+        # GitHub Release and tags if its Release PR was just merged
+        uses: changesets/action@c48e67d110a68bc90ccf1098e9646092baacaa87 # v1
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -1,17 +1,20 @@
-# Initial setup
+# Contributing to Endo
+
+## Initial setup
 
 ```sh
 git clone git@github.com:endojs/endo.git
 cd endo
 yarn
 ```
 
-Endo is a yarn workspaces repository. Running yarn in the root will install and hoist most dependencies up to the root `node_modules`.
+Endo is a yarn workspaces repository. Running yarn in the root will install and
+hoist most dependencies up to the root `node_modules`.
 
 Note: running yarn `--ignore-scripts` will not complete the setup of SES.
 Note: Endo uses `lerna` only for releasing. `lerna bootstrap` is unlikely to work.
 
-## Action pinning
+### Action pinning
 
 GitHub Actions are pinned to commit SHAs.
 Run `node scripts/update-action-pins.mjs` to refresh patch/minor pins.
@@ -23,21 +26,21 @@ If no version comment exists, it infers the latest tag for that action.
 CI enforces pinning with `node scripts/update-action-pins.mjs --check-pins`.
 If this check fails, run the updater and commit the resulting changes.
 
-## Creating a new package
+### Creating a new package
 
 Run <code>[scripts/create-package.sh](./scripts/create-package.sh) $name</code>,
 then update the resulting README.md, package.json (specifically setting
 `description` and [if appropriate] removing `"private": false`), index.js, and
 index.test.js files.
 
-## Markdown Style Guide
+### Markdown Style Guide
 
 When writing Markdown documentation:
 
-* Wrap lines at 80 to 100 columns for readability in terminal editors.
-* Start each sentence on a new line.
+- Wrap lines at 80 to 100 columns for readability in terminal editors.
+- Start each sentence on a new line.
   This ensures changes in one sentence do not cascade into the next in diffs.
-* Starting sentences on new lines also obviates any question of whether to use
+- Starting sentences on new lines also obviates any question of whether to use
   one or two spaces after a period.
 
 Example:
@@ -60,175 +63,83 @@ uses a different Markdown flavor for those contexts.
 Changes to `ses` require a `yarn build` to be reflected in any dependency where `import 'ses';` appears. Use `yarn build` under `packages/ses` to refresh the build.
 Everything else is wired up thanks to workspaces, so no need to run installs in other packages.
 
-# Making a Release
-
-* Review the [next release](
-https://github.com/endojs/endo/labels/next-release
-) label for additional tasks or pending changes particular to this release.
-
-* Do not release from a Git workspace.
-  In a Git workspace, `.git` is a file and not a directory.
-  At time of writing, Lerna does not account for Git workspaces when it looks
-  up the repository location.
-
-* Create a release branch.
-
-  ```sh
-  now=`date -u +%Y-%m-%d-%H-%M-%S`
-  git checkout -b release-$now
-  ```
-
-* Create the release CHANGELOGs.
-
-  ```sh
-  yarn lerna version --no-push --conventional-graduate --no-git-tag-version
-  ```
-
-  Use `--conventional-prerelease` instead of `--conventional-graduate` if you
-  just want to generate a dev release.
-
-* Commit the results.
-
-  ```sh
-  git commit -am 'chore: lerna version'
-  ```
-
-* Identify `NEWS.md` files that need to be updated.
-  Ensure `NEWS.md` captures all user-visible changes in prose that are
-  user-relevant.
-
-  ```sh
-  git grep '# Next'
-  ```
-
-  For each of these files, copy the version number and timestamp from the
-  adjacent `CHANGELOG.md` generated in the previous step.
-  For example,
-
-  ```diff
-  -# Next release
-  +# 0.5.1 (2021-08-12)
-  ```
+## Using Changesets
 
-  Also, capture these into a release notes document, where each heading
-  is the name of the package and the version number instead of the
-  version number and release date, like so:
+Endo uses [Changesets](https://github.com/changesets/changesets) to manage
+versioning and changelogs.
+A **changeset** is a Markdown file in the `.changeset/` directory that captures:
 
-  ```
-  # `ses` 1.0.0
-  ```
+- Which packages need to be released
+- The [semver](https://semver.org/) bump type (major, minor, or patch)
+- A changelog entry describing the change
 
-  In the release notes document, we do not manually wrap long lines.
-  All paragraphs should be joined into long lines, since Github uses a
-  different flavor of Markdown for descriptions and release notes.
+Changesets are "intents to release" that accumulate until maintainers cut a
+release.
+The changeset files themselves are temporary—when a release is cut, they are
+consumed and removed from version control, with their contents incorporated into
+each package's `CHANGELOG.md`.
 
-* Commit the results.
+This approach automates version bumping across the monorepo (including internal
+dependency updates) and generates changelogs automatically, while keeping humans
+in the loop to review and edit release notes before publishing.
 
-  ```sh
-  git commit -am 'docs: Update release notes'
-  ```
+Contributors make versioning decisions _at contribution time_ (i.e. _in the PR
+itself_), when the context is fresh.
 
-* Update `yarn.lock`.
+### Adding a Changeset
 
-  ```sh
-  yarn
-  git commit -um 'chore: Update yarn.lock'
-  ```
+When your PR includes changes that should be released, add a changeset:
 
-* Push the branch.
+1. Run `yarn changeset`
+2. Select the affected packages (use arrow keys to navigate, space to select,
+   enter to confirm)
+3. Choose the appropriate bump type for each package
+4. Write a clear, complete description of the change—what changed, why, and any
+   migration notes if needed. Consider security and performance implications.
+   This text will appear verbatim in `CHANGELOG.md`, so make it useful for
+   consumers of the package.
+5. Commit the generated `.changeset/*.md` file with your PR
 
-  ```sh
-  git push -u origin release-$now
-  ```
+> Do not be alarmed by the unique, auto-generated names of the changeset files!
+> This is expected.
 
-* Create a pull request and request a review, using the release notes
-  from above as the description.
-  This is an opportunity to:
+### Editing a Changeset
 
-  - verify that the changes pass tests under continuous integration,
-  - reflect on whether the automatically chosen version numbers tell an
-    accurate story about the backward and mutual compatibility of the packages
-    you are about to publish,
-  - and to verify that all user-facing changes are noted in the NEWS.md files
-    with appropriate migration advice when necessary.
+You typically want to do this _before_ your PR lands, but all you need to do is
+find the changeset file in `.changeset/`, edit it, and commit.
 
-* When your reviewer has approved your release, use `git rebase -i
-  origin/master` to remove the automatically generated `chore: lerna version`
-  commit.
+### Do I Need a Changeset?
 
-* Recreate the changelogs with the current date *and* generate tags for the new
-  versions. This is the effect of removing the `--no-git-tag-version` flag.
+Generally, you need a changeset only if your PR contains **user-facing changes**
+to a package—bug fixes, new features, breaking changes, or other modifications
+that consumers of the package would notice.
 
-  ```sh
-  yarn lerna version --no-push --conventional-graduate
-  ```
+You typically **do not** need a changeset for:
 
-* Update `yarn.lock`.
+- Documentation-only changes
+- Test additions or fixes
+- CI/build configuration changes
+- Refactoring that doesn't change public behavior
 
-  ```sh
-  yarn
-  git commit -um 'chore: Update yarn.lock'
-  ```
+The helpful [changeset-bot](https://github.com/apps/changeset-bot) will comment
+on your PR if no changeset is present, but this won't block merging.  
 
-* Publish the versions to npm.
-  Being a member of the project or organization and having two-factor
-  authentication may be necessary. It may be necessary to login with
-  `npm login`. You can check with `npm whoami`.
+> [!TIP]
+>
+> When in doubt, ask a friendly maintainer. Avoid the unfriendly ones.
 
-  ```sh
-  npm whoami
-  # if it does not show you logged in, then do
-  npm login
-  # two factor authentication stuff
-  yarn lerna publish from-package
-  # repeat this command until all packages are successfully published
-  ```
+### Release Workflow (For Maintainers)
 
-* To verify that packages were published, go to the npm web page for the
-  package, for example
-  [https://www.npmjs.com/package/ses](https://www.npmjs.com/package/ses).
-  ***However*** do not be alarmed if it does not show your new version for
-  a distressingly long time. Instead you can verify the version with
+The release process works as follows:
 
-  ```sh
-  npm view ses
-  ```
-
-* Force push these changes back to the pull request branch.
-
-  ```sh
-  git push origin -f release-$now
-  ```
-
-* Merge the release PR into master.
-  DO NOT REBASE OR SQUASH OR YOU WILL LOSE REFERENCES TO YOUR TAGS.
-
-  Notice the little triangle on the merge button and select "Create a merge
-  commit" from the drop down menu.
-  Do not rebase.
-  Do not squash.
-  Rebasing or squashing will remove the tag from the history of the `master`
-  branch.
-
-* Selecting "Create a merge commit" in that drop down is sticky. Assuming you
-  normally want "Squash and merge", be sure to set it back to that at your
-  next opportunity.
-
-* Push the released tags to Github.
-
-  ```sh
-  git tag -l | egrep -e '@[0-9]+\.[0-9]+\.[0-9]+$' | xargs git push origin
-  ```
-
-* Go to https://github.com/endojs/endo/releases and create a new release
-  using the latest tag for `ses` as the reference tag, and the release
-  notes you prepared for the pull request description.
-
-## More information
-
-To get help for the command-line options that will affect these commands, use:
-
-```sh
-yarn lerna version --help
-yarn lerna publish --help
-```
+1. As changesets accumulate on `master`, the `changesets/action` GitHub Action
+   (see [.github/workflows/release.yml](.github/workflows/release.yml))
+   automatically creates and maintains a **Release PR** titled "Version
+   Packages"
+2. This Release PR applies all pending changesets; it bumps versions, updates
+   `CHANGELOG.md` files, and deletes the consumed changeset files
+3. Maintainers review the Release PR to verify versions and changelog entries
+   look correct. Maintainer will approve and/or merge when ready.
+   Merging will also create tags and GitHub Releases for each affected package.
+4. After merging the Release PR, pull `master` and run `yarn release:npm` to
+   publish the updated packages to npm.
diff --git a/package.json b/package.json
@@ -9,6 +9,8 @@
   },
   "packageManager": "yarn@4.10.3",
   "devDependencies": {
+    "@changesets/changelog-github": "^0.5.2",
+    "@changesets/cli": "^2.29.8",
     "@endo/ses-ava": "workspace:^",
     "@jessie.js/eslint-plugin": "^0.4.2",
     "@lavamoat/allow-scripts": "^3.3.5",
@@ -46,6 +48,7 @@
     "lint:fix": "yarn lint:eslint -- --fix",
     "lint:workspaces:fix": "yarn workspaces foreach --all run lint-fix",
     "lint:prettier": "prettier --check .github packages",
+    "release:npm": "lerna publish from-package",
     "test": "yarn workspaces foreach --all --exclude @endo/skel run test",
     "test:c8": "yarn workspaces foreach --all run test:c8",
     "test:xs": "yarn workspaces foreach --all run test:xs",
diff --git a/yarn.lock b/yarn.lock
