Changesets

Changesets

Last updated April 19 2023

We use a modified version of the changesets workflow to track changes that we want to communicate to customers or partners.

A changeset is a separate concept from either a changelog or release notes, but they are related. The changeset carries with it two key bits of information:

• the packages affected by the change
• a Markdown-formatted description of the change

Storing this information directly in git metadata such as commits is problematic because once written, git metadata cannot be changed without disrupting other contributors. This means that when we do a release and generate the changelogs, any tweaks we want to make must be made and stored elsewhere. Changesets allow us to review and fix change announcements just like code. Changesets are stored on the file system in a .changeset folder in the root of the release group (or package, for independent packages).

A changeset is a Markdown file with YAML front matter. The contents of the Markdown is the change summary which will be written to the changelog and the YAML front matter describes what packages have changed and what semver bump types they should be (for the FluidFramework repo the bump types are determined by the target branch).

---
"@myproject/cli": minor
"@myproject/core": minor
---

Change all the things

This is useful because it breaks change tracking into two steps:

1. Adding a changeset - can be done in a PR, by a contributor, while the change is fresh in their mind.
2. Releasing/versioning - combines all changesets and writes changelogs, which can then be reviewed in aggregate.

Note: The default changesets workflow and tools, which we are using, include the "bump type" (major | minor | patch) for each package in the changeset. Within the FluidFramework repo, the bump type is determined by the branch the change is merged to.

Changesets and CI

Changesets are not fully automated yet. For now, PRs that need changesets are manually identified and labeled with the changeset-required label.

• If the PR is labeled changeset-required (only added manually at this point), then it will be checked for a changeset. If one is missing, then a comment will be added to the PR saying that a changeset is needed.
• If a PR is labeled changeset-required and has a changeset, it will be labeled changeset-present.

A note about tools

We intentionally use as little custom tooling as possible in our implementation of changesets. We are re-using the changesets CLI and the schema they defined, even though it does not match our needs fully. This is an intentional choice motivated by two things: (1) developing and maintaining custom tooling is costly and (2) our needs remain quite dynamic, and it is foolish to believe we know enough about our needs to invest heavily in custom tools and "get it right." Rather, we are using the tools as they are so that we can more quickly learn.

You should not read this, though, as a reason to not complain about friction with the tools! We need to know what works and what doesn't so we can make better decisions about what customizations we should invest in. So please share your feedback about those rough edges with us!

Adding a changeset to a PR

Note: the following only applies to the client release group. For independent packages or other release groups, contact @tylerbutler.

You can add a changeset to your PRs manually or using the pnpm changeset command.

Adding a changeset using pnpm changeset

To add a changeset, run pnpm changeset from the root of the repo. You will be prompted to select the affected packages and their bump types. By default the CLI will show what packages have changed relative to main to make it easier to select affected packages. The output is completely editable after the CLI is used so don't worry about "getting it right." You can always fix it up!

Manually adding a changeset

To manually add a changeset, add a randomly named markdown file to the .changeset folder in the root of the repo. Make sure to include the metadata about what packages are affected!

Adding an empty changeset

You can add an empty changeset using the command pnpm changeset --empty. Make sure to add details about the change, including the metadata about what packages are affected!

How do I know what packages to include in the changeset?

Each package in the changeset will have a changelog entry with the contents of the changeset. In other words, if you list a package in a changeset, you're saying that the contents of the changeset are relevant to that package. You do not need to include every package that was changed in a given PR. For example, if you deprecate a class in packageA and replace the use of the deprecated class in packageB, then packageB probably shouldn't be included in the changeset, while packageA should be.

Which PRs require changesets?

Any change that should be communicated to customers or partners should have a changeset. Stated differently, changes without a changeset are "invisible" to customers; changesets are how we track what needs to be communicated with partners and customers. We are discussing how to automate flagging some PRs, but for now it's manual.

Do I need to add a changeset with the change, or can I add it later?

You should add a changeset with every change that should be communicated, even if it is empty. The contents of the changeset can be updated at any time before release, but adding the changeset with the relevant change makes it easier to link commits to changelog entries. You can always add an empty changeset if you really don't know what to communicate to customers yet.

When will we release a version using the changesets?

We are aiming for the 2.0.0-internal.5.0.0 major release.

More questions?

Our changesets FAQ may answer them. If not, contact @tylerbutler.