Skip to content

Latest commit

 

History

History
237 lines (175 loc) · 10.3 KB

Release_Protocol.md

File metadata and controls

237 lines (175 loc) · 10.3 KB
Raw

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 bids-standard/bids-specification repository and have cloned your fork locally to a directory called bids-specification.

NOTE: Before you start a release, you have to ensure that the automatically generated changelog is up to date. See the relevant section in CONTRIBUTING.md for further information. In practice this means ensuring that the most recently merged pull request was merged into the master branch using the "Merge commit" option.

1. Fetch the latest version of the master branch of the BIDS-specification

You should have a remote, which we will call upstream, for the bids-standard/bids-specification repository:

git remote get-url upstream
git@github.com:bids-standard/bids-specification.git

If you do not, add it with:

cd bids-specification
git remote add upstream git@github.com:bids-standard/bids-specification.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, contributors list, previous version URLs, and the Changelog

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://bids-specification.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 specification. 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. dev-to-stable

Additionally, implement the same change in the version name perform above in the src/schema/BIDS_VERSION file.

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.

Please change the previous version links from GitHub to ReadTheDocs. In the figure below, we update v1.2.2. github-to-rtd

Review src/CHANGES.md to ensure that the document produces a changelog that is useful to a reader of the specification. 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. You can also make use of the exclude-from-changelog label. Adding this label to PRs in the GitHub web interface will prevent the changelog generator from considering this item for inclusion in the changelog.

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/appendices/contributors.md src/schema/BIDS_VERSION
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 notes:

  1. The pull request title must be named "REL: vX.Y.Z" (for example, "REL: v1.2.0")
  2. The pull request must get a GitHub label called exclude-from-changelog

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 among BIDS Maintainers.

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/<version> branch:

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

5. Set release date and merge

On the day of release, please ensure the release branch aligns with the master branch. 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://bids-specification.readthedocs.io/en/v1.2.0/)
+ ## [v1.2.0](https://bids-specification.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.

6. Get the built PDF

Upon each commit to the master branch, CircleCI builds a PDF version of the specification (see .circleci/config.yml and the pdf_build_src directory).

So after merging the new "stable" version into master, wait for the CircleCI jobs to finish and then check the built PDF using the following steps:

  1. Go to the list of recent commits
  2. Click on the "CI checks" for the most recent commit (should be a green checkmark)
  3. From the list of CI checks, click on the one called: Check the rendered PDF version here!
  4. Download the PDF and check that the date and version on the first page are as expected
  5. Hold the PDF ready for upload to our Zenodo archive (see the Uploading the stable PDF to Zenodo step below)

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: GH-release-1

Click Draft a new release:

GH-release-2

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

GH-release-3

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 commit to master with the title REL: <version>-dev. This should be the first commit in the new version. This process is illustrated below.

stable-to-dev

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.

Additionally, the same version name set above in mkdocs.yaml should be set in the src/schema/BIDS_VERSION schema version file.

10. Uploading the stable PDF to Zenodo

  1. Open a private browser window
  2. Log into https://github.com with the bids-maintenance user (credentials are available from the BIDS maintainer group)
  3. Open a new tab at https://zenodo.org and "log in via GitHub", you'll then be on the bids-maintenance Zenodo account
  4. Navigate to the archive of our BIDS specification PDFs
  5. Click on "add new version"
  6. For a new version, upload the new PDF, naming it consistently with the other PDFs: BIDS-Specification-vX.X.X.pdf (replace X.X.X with the new version)
  7. Remove all other files from the upload
  8. Edit the following fields:
    1. publication date
    2. version
  9. Double check that everything is in order, then save and publish

11. Sharing news of the release

Please share news of the release on the identified platforms. Please use our previous release posts as a guide.