Change files

There are very popular and excellent packages available which manage package versioning based on commit messages. beachball works differently, using something called a change file.

What is a change file?

Change files are generated by the beachball change command and live under the /change folder. They look something like this:

{
  "comment": "Upgrading React to 16.8.x to use hooks",
  "type": "minor",
  "packageName": "my-amazing-app",
  "email": "me@me.me"
}

beachball then uses the change files during publishing to determine how to bump package versions, and what content should be in the changelog.

The advantage of using .json files rather than commit messages is that it's very easy to see visual diffs of these files in a PR, so reviewers can verify that the change type and message are correct.

For example, a reviewer might remind the author that a certain new API has been introduced and that the change ought to be a minor. The author can then modify the change file without having to amend history of a commit!

Grouped change files

In a monorepo, it's usually recommended to set groupChanges: true in your beachball config file. This stores the change info for all of a branch's changed packages in a single change file, rather than creating many individual change files.

Note: groupChanges won't work in the rare case that your repo has multiple sets of packages which are published separately using different scope options.

Generating a change file

After making some commits, it's time to create a change file. Change files are generated with the beachball change command. (In a monorepo, this should only be run at the repo root.)

Assuming you've defined the change wrapper script suggested on the installation page, run one of the following commands:

# for npm
$ npm run change
# for yarn
$ yarn change

If you don't already have a change file for this branch and package, it will ask you to enter a description and a change type (in a monorepo, it will ask for each changed package).

• For the description, beachball will provide a list of recent commit messages to choose from, or you can type a custom message.
• Choose the correct type using semantic versioning rules.

After you've answered those questions, a change file similar to the example above is created and committed in your branch under /change.

If you prefer, you can specify the change type and message on the command line. (In a monorepo, the specified type and message will be used for all changed packages.)

# for npm
$ npm run change -- --type minor --message "Upgrading React to 16.8.x to use hooks"
# for yarn
$ yarn change --type minor --message "Upgrading React to 16.8.x to use hooks"

Validating change files

Your PR build should include a step that calls beachball check to validate that change files are included.

Assuming you've defined the checkchange wrapper script suggested on the installation page, add a step to your PR build as follows.

# For GitHub Actions:
### With npm:
- run: npm run checkchange
### With yarn:
- run: yarn checkchange

# For Azure Pipelines:
### With npm:
- script: npm run checkchange
### With yarn:
- script: yarn checkchange

An alternative if desired is to define a separate required workflow/pipeline which skips the main install step and only runs npx beachball check. This has the advantage of providing faster validation and not blocking the main PR build (and hiding any later build/test/lint errors) simply for missing change files.

To prevent change files from being required for changes that will never affect the published package (such as tests, snapshots, or certain config files), use the ignorePatterns option.

Note: In the past, it was necessary to check out the repo's whole history for beachball check to work properly (such as setting fetch-depth: 0 in actions/checkout for GitHub workflows). This should no longer be needed because if beachball detects a shallow clone, it will automatically fetch more history, and exit with an error if the current branch and target branch don't appear to share history.