[Fuente: https://github.com/changesets/changesets]

A tool to manage versioning and changelogs with a focus on multi-package repositories

The changesets workflow is designed to help when people are making changes, all the way through to publishing. It lets contributors declare how their changes should be released, then we automate updating package versions, and changelogs, and publishing new versions of packages based on the provided information.

Changesets has a focus on solving these problems for multi-package repositories, and keeps packages that rely on each other within the multi-package repository up-to-date, as well as making it easy to make changes to groups of packages.

How do we do that?

A changeset is an intent to release a set of packages at particular semver bump types with a summary of the changes made.

The @changesets/cli package allows you to write changeset files as you make changes, then combine any number of changesets into a release, that flattens the bump-types into a single release per package, handles internal dependencies in a multi-package-repository, and updates changelogs, as well as release all updated packages from a mono-repository with one command.

How do I get started?

If you just want to jump in to using changesets, the Intro to using changesets and @changesets/cli docs are where you should head.

If you want a detailed explanation of the the concepts behind changesets, or to understand how you would build on top of changesets, check out our detailed-explanation.

We also have a dictionary.

Using Changesets

Changesets are designed to make your workflows easier, by allowing the person making contributions to make key decisions when they are making their contribution. Changesets hold two key bits of information: a version type (following semver), and change information to be added to a changelog.

In addition, changesets were originally designed for implementation in bolt monorepos. As such, in a monorepo context, changesets will handle bumping dependencies of changed packages, if that is required.

This guide is aimed at package maintainers adding changesets as a tool. For the information relevant to contributors, see adding a changeset.

The overall tool after initialization should lead to a loop that looks like:

1. Changesets added along with each change
2. The version command is run when a release is ready, and the changes are verified
3. The publish command is run afterwards.

The second two steps can be made part of a CI process.

Add the changeset tool

npm install @changesets/cli && npx changeset init

or

yarn add @changesets/cli && yarn changeset init

Adding changesets

npx changeset

or

yarn changeset

Note: You can run changeset add to add a changeset if you want to, but running Changesets without any command works as well.

Versioning and publishing

Once you decide you want to do a release, you can run

npx changeset version

or

yarn changeset version

This consumes all changesets, and updates to the most appropriate semver version based on those changesets. It also writes changelog entries for each consumed changeset.

We recommend at this step reviewing both the changelog entries and the version changes for packages. Once you are confident that these are correct, and have made any necessary tweeks to changelogs, you can publish your packages:

npx changeset publish

or

yarn changeset publish

This will run npm publish in each package that is of a later version than the one currently listed on npm.

Some handy advice

Not every change requires a changeset

Since changesets are focused on releases and changelogs, changes to your repository that don’t require these won’t need a changeset. As such, we recommend not adding a blocking element to contributions in the absence of a changeset.

A Detailed Explanation of Changesets

Below, you will find a detailed explanation of what changesets are, and how they are being thought about.

The problem:

When organising the release of packages, you may end up wanting to group several changes together written by different people and/or over a relatively large period of time. The best time to capture this information is when submitting a PR (when it is fresh in your mind), not when you eventually go to batch and release these changes.

Git is a bad place to store this information, as it discourages writing detailed change descriptions – you want to allow people to provide as much documentation for the change as they want.

The solution, Changesets:

The best way to think about a changeset as separate to either a changelog or a version bump is that a changeset is an ‘intent to change’. The intent to change carries with it two key bits of information:

• versioning
• changelogs

As it is an intent to change, the relevant versioning information is:

• ‘major’ | ‘minor’ | ‘patch’

In addition, within a mono-repository, we can encode information about any other packages in the mono-repository that should be re-released to consume this change. This ensures that if you upgrade latest of all the packages, they are all compatible. The current implementation is heavily informed by bolt’s opinion on version compatibility.

• changelog information can be stored as a markdown snippet.

As storing this information directly in git is problematic, we store it in the file system using the following structure:

-| .changeset/
-|-| UNIQUE_ID.md

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

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

Change all the things

This is useful because it breaks versioning 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. Versioning – combines all changesets, creates one version bump for each package based on the maximum version bump of each package, and updates dependencies where needed, write changelogs. Can then be reviewed as an aggregate.

The tooling that makes this worthwhile

1. CLI generation of new changesets
2. Automated consumption of changesets to do versioning
3. Detection + surfacing of changesets in PRs

A tool to publish multiple packages from a mono-repo is also important, however does not need to be linked to this.

See this blog post I need to write this, this link goes nowhere

Benefits to single-package repos

Changesets are designed first and foremost to handle versioning in multi-package repos, where interdependencies flowing through the system are important to understand and capture.

Conceptually though, the benefits of changesets are detacheable from this. I think this process overall leads to an improvement in Pull Requests that helps increase confidence in versioning decisions and changelog entries.