This document is intended to help consolidate the practices we are using to develop and maintain Cats. Its primary audience is Cats maintainers who may need to close issues, merge PRs, do releases, or understand how these things work.
Merging pull requests
Pull requests currently require two sign-offs from Cats maintainers. Community member sign-offs are appreciated as votes of confidence but don't usually count toward this total unless the commenter has already been involved with the area of code in question.
When fixing typos, improving documentation or minor build fix only one sign-off is required (although for major edits waiting for two may be preferable).
For serious emergencies or work on the build which can't easily be reviewed or tested, pushing directly to master may be OK (but is definitely not encouraged). In these cases it's best to comment in Gitter or elsewhere about what happened and what was done.
1.0.0 release, Cats adopted the MAJOR.MINOR.PATCH
Semantic Versioning 2.0.0. In semantic versioning,
Backward binary compatibility is maintained between PATCH AND MINOR versions.
The main rules are:
- PATCH version Z (x.y.Z | x > 0) MUST be incremented if only backwards compatible bug fixes are introduced.
- MINOR version Y (x.Y.z | x > 0) MUST be incremented if new, binary backwards compatible functionality is introduced to the public API. It MUST be incremented if any public API functionality is marked as deprecated.
- Source breaking but binary compatible changes are allowed between MINOR versions.
- Binary backward breaking changes are ONLY allowed between MAJOR versions.
- For other scenarios, refer to Semantic Versioning 2.0.0.
For a new MINOR version release, it's preferred to release a Release Candidate for public testing. If there are no regressions or new bugs discovered, the new MINOR version should be released within a couple of weeks, with no significant changes in between.
Before the actual release, we need to make sure all merged PRs are properly assigned with the correct Github Milestone and labels.
Make sure a milestone corresponding to the to-be released version exists on Github.
Then use the following search to gather all merged PRs to be released: https://github.com/typelevel/cats/pulls?utf8=%E2%9C%93&q=merged%3A%3E2019-05-29+ replace
2019-05-29with the last release date.
For PRs that add no value to the code or documentation or build, for example, community announcements or additions to adopter list, we do not include them in the release notes. Assign these PRs a special milestone:
Excluded from release notes
Assign the rest PRs with the target milestone and one or more of the following labels:
For non-milestone releases (e.g. 2.0.0-M1), we shall release from a release branch. For each MINOR version, we shall have a corresponding branch, e.g.
2.1.x. There are 2 main benefits for this:
- Since we need to go through at least 1 release candidate release, having a release branch makes it easier to incorporate potential fixes and release the official release later.
- The master branch of Cats is protected. This means sbt-release cannot push post release commits and more importantly tags directly to master. It can with a release branch, and a PR can be submitted to merge the release branch back into master.
Before the release, the tests and other validation must be passing.
Currently, the best way to release Cats is:
+ cleanto ensure a clean start.
+ packageto ensure everything builds.
release, which will validate tests/code, etc.
release should do all of these things but for now the
individual steps are necessary.)
You will need to enter a GPG password to sign the artifacts correctly, and you will also need to have Sonatype credentials to publish the artifacts. The release process should take care of everything, including releasing the artifacts on Sonatype.
If the Sonatype publishing fails, but the artifacts were uploaded, you
can finish the release manually using the Sonatype web site. In that
case you will also need to do
git push --tags origin master to push
the new version's tags.
(In the future we may want to create branches for major versions,
v1.x. For now we don't have these.)
The release will take a few hours to sync to Maven Central. It's usually better to hold off announcing the release until this sync has happened. (Before the sync, users may not be able to resolve the new version.)
After the release occurs, you will need to update the documentation. Here is a list of the places that will definitely need to be updated:
README.md: update version numbers
AUTHORS.md: add new contributors
CHANGES.md: summarize changes since last release
(Other changes may be necessary, especially for large releases.)
If the Pre-release step is properly done, meaning all released PRs are properly assigned with label and milestone, you can use a script to generate the release note. Follow the doc in the script for instructions.
Alternatively, you can get a list of changes between release tags
git log v0.1.2..v0.2.0. Scanning this list of commit
messages is a good way to get a summary of what happened, and manually write it up.
Once the relevant documentation changes have been committed, new release notes should be added. You can add a release by clicking the "Draft a new release" button on that page, or if the relevant release already exists, you can click "Edit release".
Ideally this document will evolve and grow as the project matures. Pull requests to add sections explaining how maintenance occurs (or should occur) are very welcome.