Release process

The majority of our release process is automated by the changesets tool and our changeset-publish.yml GitHub Actions workflow.

What is a changeset?

A changeset is a small markdown file in the .changeset/ directory that describes the changes in a release. It is used to generate the changelog and the version bump. There is one changeset file for each "set of changes" i.e. a pull request. Every pull request requires a changeset file (enforced by the changeset bot).

If your PR is a consumer-facing change and should be mentioned in the release notes, create a changeset file like this:

pnpm changeset

The changeset cli will prompt you for the type of change (patch/minor/major), the affected packages (@adobe/alloy? @adobe/alloy-core? @adobe/alloy-sandbox-browser?) and a short summary of the changes.

Then commit the changeset file and push it to your branch.

Note

Only changes with a non-empty changeset are published. If a change only has an empty changeset (or no written changeset at all), it will not be published.

I want to…

…release an beta version

Good news! You don't need to do anything. "beta" prerelease mode is the default mode. Beta releases happen with every merge to main. They are published to the beta and next npm tags.

…release a stable version

First, you need to set the prerelease mode to stable.

git switch main
git switch --create 2.31.1
pnpm changeset pre exit
git push origin 2.31.1

Then create the PR and merge it into main.

This will move the publish process into "stable" mode. The version will be bumped to a number like 2.31.1 and published to the latest npm tag.

After the PR is merged and the version is published, the publish process will automatically move back to prerelease mode using the beta tag, ensuring that we are always releasing new versions.

…edit the release notes after a changeset has been merged.

No problem! Since changeset files are just markdown files, just edit the corresponding file in the .changeset/ directory and commit the changes. If you can't find the corresponding changeset file, i.e. it was from before the previous stable release, just edit the CHANGELOG.md file.

What happens when I merge a PR?

When you merge a PR into main, the changeset-publish.yml GitHub Actions workflow is triggered. Here's what happens:

1. The workflow determines the release mode (prerelease/stable) and the version number.

2. The workflow requests approval to publish the new version.

3. Once approved, the workflow runs pnpm changeset version to bump package versions and update CHANGELOG.md files based on the pending changesets.

4. The packages are built and published to npm with the appropriate tags:

   • Prerelease → beta and next tags
   • Stable → latest tag

5. Browser-related artifacts are uploaded to the CDN.

6. A GitHub Release is created with the release notes extracted from CHANGELOG.md.

7. For stable releases only, the workflow automatically re-enters beta prerelease mode so we're ready for the next development cycle.

All of these steps are automated. The only manual step is approving the publish in the GitHub Actions UI.