Release_Protocol.md

Release Procedure

When it is time to release, use a pull request to put the repository into a releasable state, allowing testing and edits prior to merging to master. The following procedure ensures a predictable release.

The protocol assumes that you have a fork of the dbic/handbook repository and have cloned your fork locally to a directory called handbook.

1. Fetch the latest version of the master branch of the DBIC-handbook

You should have a remote, which we will call upstream, for the dbic/handbook repository:

$ git remote get-url upstream
git@github.com:dbic/handbook.git

If you do not, add it with:

$ cd handbook
$ git remote add upstream git@github.com:dbic/handbook.git

Fetch the current repository state and create a new rel/<version> branch based on upstream/master. For example, if releasing version 1.2.0:

$ git fetch upstream
$ git checkout -b rel/1.2.0 upstream/master

2. Update the version and the contributors list

Change the "Unreleased" heading in src/CHANGES.md to v<version>, and link to the target ReadTheDocs URL. If the target release date is known, include the date in YYYY-MM-DD in parentheses after the link.

- ## Unreleased
+ ## [v1.2.0](https://dbic.readthedocs.io/en/v1.2.0/) (2019-03-04)

The date can be changed or added later, so accurate prediction is not necessary.

Remove the -dev from the version in mkdocs.yml configuration, so the title will be correct for the released handbook. If the version preceding the -dev is not the target version, update the version as well. In the figure below, we update v1.2.0-dev to v1.2.0.

Note: this will make our continuous integration (CircleCI) fail. This fails because the URL of the new ReadTheDocs rendering has not been generated at this time. It will be generated once the GitHub release has been completed.

Synchronize the Contributors appendix with the Contributors wiki page to ensure all contributors are duly credited. Be sure not to remove credits if both have been edited.

3. Commit changes and push to upstream

By pushing rel/ branches to the main repository, the chances of continuous integration discrepancies is reduced.

$ git add src/CHANGES.md mkdocs.yml src/99-appendices/01-contributors.md
$ git commit -m 'REL: v1.2.0'
$ git push -u upstream rel/1.2.0

4. Open a pull request against the master branch

Important note: The pull request title must be named "REL: vX.Y.Z" (e.g., "REL: v1.2.0").

This will open a period of discussion for 5 business days regarding if we are ready to release.

Minor revisions may be made using GitHub's suggestion feature. For larger changes, pull requests should be made against master.

Merging other pull requests during this period requires agreement in this discussion.

There are no hard-and-fast rules for what other pull requests might be merged, but the focus should generally be on achieving a self-consistent, backwards-compatible document. For example, if an inconsistency is noticed, a PR might be necessary to resolve it. Merging an entire BEP would likely lead to greater uncertainty about self-consistency, and should probably wait.

If master is updated, it should be merged into the rel/<verison> branch:

$ get fetch upstream
$ git checkout rel/1.2.0
$ git merge upstream/master
$ git push rel/1.2.0

5. Clean the changelog

Review src/CHANGES.md to ensure that the document produces a changelog that is useful to a reader of the handbook. For example, several small PRs fixing typos might be merged into a single line-item, or less important changes might be moved down the list to ensure that large changes are more prominent.

6. Set release date and merge

On the day of release, the current date should be added to/updated in the changelog in the form YYYY-MM-DD. The date should be placed after the link to the versioned URL. For example:

- ## [v1.2.0](https://dbic.readthedocs.io/en/v1.2.0/)
+ ## [v1.2.0](https://dbic.readthedocs.io/en/v1.2.0/) (2019-03-04)

Verify that the pull request title matches "REL: vX.Y.Z" and merge the pull request.

7. Tag the release

GitHub's release mechanism does not have all of the features we need, so manually tag the release in your local repository. To do this, fetch the current state of upstream (see step 1), tag upstream/master, and push the tag to upstream.

$ git fetch upstream
$ git tag -a -m "v1.2.0 (2019-03-04)" v1.2.0 upstream/master
$ git push upstream v1.2.0

There are four components to the tag command:

1. -a- indicates that we want to use an annotated tag, which will ensure that git describe works nicely with the repository.
2. -m <message> is the message that will be saved with the tag.
3. v<version> is the name of the release and the tag.
4. upstream/master instructs git to tag the most recent commit on the master branch of the upstream remote.

8. Create a GitHub release

Some GitHub processes may only trigger on a GitHub release, rather than a tag push. To make a GitHub release, go to the Releases page:

Click Draft a new release:

Set the tag version and release title to "vX.Y.Z", and paste the current changelog as the description:

Click "Publish release".

Verify ReadTheDocs builds complete and publish. If needed, manually trigger builds for stable and the most recent tag.

9. Edit the mkdocs.yml file site_name to set a new development version

Please submit a PR with the title REL: <version>-dev. This should be the first merged PR in the new version. This process is illustrated below.

Note that the development version number should be larger than the last release, with the version of the next intended release, followed by -dev. For example, after the 1.3.0 release, either 1.3.1-dev or 1.4.0-dev would be reasonable, based on the expected next version.