Skip to content

Latest commit

 

History

History
264 lines (195 loc) · 10.9 KB

Release_Protocol.md

File metadata and controls

264 lines (195 loc) · 10.9 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
[email protected]:bids-standard/bids-specification.git

If you do not, add it with:

cd bids-specification
git remote add upstream [email protected]: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

2.1 Update the version

Update the version in CITATION.cff.

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.

2.2 Update the contributors list

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.

  • add new contributors info to the tools/new_contributors.tsv file.
  • make sure that you have installed
    • all the python packages listed in tools/requirements.txt
    • the allcontributors package
  • run:
make update_contributors
  • you may need to fix some errors in the contributions names in case of crash
  • make sure to review the changes and not commit them blindly
  • commit the changes

2.3 Update the previous version URLs

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

2.4 Update the Changelog

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.

Similarly update the version in CITATION.cff with a dev suffix.

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.