diff --git a/Release_Protocol.md b/Release_Protocol.md index 26a1ed3da1..afd931b50f 100644 --- a/Release_Protocol.md +++ b/Release_Protocol.md @@ -1,35 +1,157 @@ # Release Procedure -When a release pull request is ready to be opened, please follow this 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. -### 1. Fork/Update the most current version of the [master branch of the BIDS-specification](https://github.com/bids-standard/bids-specification/tree/master) +### 1. Fetch the latest version of the [master branch of the BIDS-specification](https://github.com/bids-standard/bids-specification/tree/master) -Please make sure your fork is the most up to date version +You should have a remote, which we will call `upstream`, for the [ +bids-standard/bids-specification](https://github.com/bids-standard/bids-specification/) repository: -### 2. Change 'Unreleased' to the version number and change the path to the versioned readthedocs rendering in the src/CHANGES.md file. One may commit this to their fork. +```Shell +$ git remote get-url upstream +git@github.com:bids-standard/bids-specification.git +``` -This process is figured below ![Unreleased-to-Version](release_images/Unreleased-to-Version.png "Unreleased-to-Version") +If you do not, add it with: -### 3. Edit the mkdocs.yml file site_name version to the new version +```Shell +$ git remote add upstream git@github.com:bids-standard/bids-specification.git +``` -This process is shown below ![dev-to-stable](release_images/site_name_release_1.2dev-1.2.png "dev-to-stable") +Fetch the current repository state and create a new `rel/` branch based on +`upstream/master`. +For example, if releasing version `1.2.0`: -### 4. Please open a pull request on the [master branch of the BIDS-specification](https://github.com/bids-standard/bids-specification/tree/master). -Important note: The pull request title **needs** to follow this protocol. REL: vX.X.X (i.e. REL: v1.1.2). There could be one or two commits in the pull request (the step 2 and 3 changes) +```Shell +$ git fetch upstream +$ git checkout -b rel/1.2.0 upstream/master +``` -### This will open a period of discussion for 5 business days regarding if we are ready to release. This will also freeze all pull request merging. +### 2. Update the version in the changelog and mkdocs.yml -If we determine we are ready to release, please have the PR submitter add an additional commit with the date in year-month-date format in parentheses after the version of the date of merging (not opening) (i.e. it should read v1.1.2 (2018-12-28)) and merge this PR. This will mark a new release. On the same day, please also do a GitHub release. To do this please see below. +Change the "Unreleased" heading in +[src/CHANGES.md](https://github.com/bids-standard/bids-specification/blob/master/src/CHANGES.md) +to `v`, 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. +```Diff +- ## 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](https://github.com/bids-standard/bids-specification/blob/master/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](release_images/site_name_release_1.2dev-1.2.png "dev-to-stable") + +### 3. Commit changes and push to upstream + +By pushing `rel/` branches to the main repository, the chances of continuous integration +discrepancies is reduced. + +```Shell +$ git add src/CHANGES.md mkdocs.yml +$ 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](https://help.github.com/en/articles/incorporating-feedback-in-your-pull-request). +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/` branch: + +```Shell +$ 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 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. + +### 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: + +```Diff +- ## [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. + +### 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`. + +```Shell +$ 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](https://git-scm.com/book/en/v2/Git-Basics-Tagging#_creating_tags), which will + ensure that [`git describe`](https://git-scm.com/docs/git-describe) works nicely with the + repository. +2. `-m ` is the message that will be saved with the tag. +3. `v` 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 +](https://github.com/bids-standard/bids-specification/releases) page: ![GH-release-1](release_images/GH-release_1.png "GH-release-1") +Click [Draft a new release](https://github.com/bids-standard/bids-specification/releases/new): + ![GH-release-2](release_images/GH-release_2.png "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](release_images/GH-release_3.png "GH-release-3") -However, if it is determined we are not ready to release, please simply close the pull request. +Click "Publish release". -### 5. Edit the mkdocs.yml file site_name to set a new development version +### 9. Edit the mkdocs.yml file site_name to set a new development version Please submit a PR with the title `REL: -dev`. This should be the first merged PR in the new version. diff --git a/release_images/GH-release_3.png b/release_images/GH-release_3.png index c4823c2ca8..224bcea291 100644 Binary files a/release_images/GH-release_3.png and b/release_images/GH-release_3.png differ