Beachball is a semantic version bumping tool and changelog generator.
Semantic versioning (or semver for short) is a notation system for package versioning. It outlays that package version notation should follow MAJOR.MINOR.PATCH. e.g. v.3.1.2 equates to a major version of 3, a minor version of 2 and a patch version of 1. For more information see: https://semver.org/
Semantic version bumping is how we increment that version in our packages. Again this is detailed significantly on https://semver.org/ so definitely check that out but in short:
- MAJOR: This indicated a breaking change has occurred. We should never have a breaking change unless we are planning a significant new release.
- MINOR: A backwards compatible new feature has been added.
- PATCH: A small, backward compatible bug fix was added.
Along with regular package version updates, we also produce alpha releases nightly, and beta releases when we are working towards a new major version release.
- Nightly Alpha versions follow the following syntax: v.#.#.#-alpha-yyyymmddHHMM
- Beta versions follow the following syntax: v.#.#.#-beta.#
See creating a release for more information.
We use beachball for three main functions:
- Produce
change
files - Bump our package versions and update sample package dependencies
- Generate changelogs
Change files are short json files created after running beachball change
. We have aliased this in our repo to simply be rush changelog
. They detail if the change was major/minor/patch/prerelease/none and also include a short description of the change that was made.
For more information on change files see: https://microsoft.github.io/beachball/concepts/change-files.html
For writing a good changelog entry for the change file see: Tips for writing meaningful changelog entries.
This is done by our github actions. If this needs to be down manually you can run npm run beachball -- bump
under common/config
.
See creating a release for more information.
This happens as part of the beachball bump
command. In our repo however we have custom changelog renderers to create a feature rich changelog with links to PRs and authors.
These custom renderers are located here: common/config/beachball/changelog-custom-renders.ts.
Pull Request builds check that the necessary change file(s) have been included in the PR and will fail if they were not checked in. To see all PR gates, view pull requests docs.
The primary beachball configuration file is at: common/config/beachball/changelog-config.ts. This is picked up by the root level beachball.config.js
.
Each package.json
must also not be marked private:true
or beachball will ignore it and may optionally contain a beachball:
section that contains package specific configuration.