Container Service Release Procedure

The release procedure here will create

• All the right commits to all the right branches of the GitHub repo: https://github.com/NrgXnat/container-service
• A release in the NRG Artifactory, containing a jar, a fat jar, a javadoc jar, and a source jar.
• A release page on the GitHub repo, which will have its own page and can also be found at the "latest" version link (https://github.com/NrgXnat/container-service/releases/latest) until another release is made.

1. Collect all changes to be released into a branch. This will often be the dev branch, but could be a special-purpose branch just for this release. Be sure to ask any developers or stakeholders if they have everything they are working on merged into the branch.
2. Ensure all the tests pass. This can be done locally if your setup permits testing with docker; the tests will also run automatically on CircleCI whenever you push to a branch on the origin repository at https://github.com/NrgXnat/container-service. See https://circleci.com/gh/NrgXnat/container-service. If the tests do not pass, the release is not ready.
3. Make a commit to this branch containing the following changes:
   1. In build.gradle find the line that begins with "version". Remove the "-SNAPSHOT" from the version identifier. Note the version for the next step.
   2. In CHANGELOG.md, under the heading for the version to be released, remove the text "Not yet released." and replace with the text "[Released ${DATE}](https://github.com/NrgXnat/container-service/releases/tag/${VERSION})." where ${DATE} and ${VERSION} should be filled in with today's date and the version noted in the previous step.
   3. The commit message should be "Bump version to ${VERSION}"
4. Check out the master branch.
5. Merge the branch to be released in "No Fast Forward" mode, with the commit message "Release version ${VERSION}". To do a no-fast-forward merge, you should use the "--no-ff" flag on the command line; there may be a way to do this in SourceTree or some other GUI git application but I do not know that. So the command should be:
   git merge --no-ff -m "Release version ${VERSION}" ${NAME OF BRANCH TO BE RELEASED}
6. Tag this commit with the version number. On the command line:
   git tag ${VERSION}
7. Push the master branch.
   git push master
8. Push the newly created tag.
   git push --tags
9. Build and upload the fat jar. On the command line, run
   ./gradlew clean fatJar publish
   NOTE: The "publish" task requires that you have your NRG Artifactory credentials stored in a local or global gradle.properties file. Your username should be stored in the key "repoUsername" and your encrypted password in the key "repoPassword". For instructions on how to get the encrypted password, watch the video on Deploying Artifacts to the XNAT Repository.
10. Create the release page. (It is possible we may automate this later, but right now it is done manually.) 
    1. Navigate your browser to the GitHub releases page: https://github.com/NrgXnat/container-service/releases
    2. Click the button to "Draft a new release".
    3. Enter ${VERSION} in the Tag version and Release title fields.
    4. Create the release notes and enter into the "Describe this release" field
       1. Enter some summary text if you want. This is optional.
       2. Copy from CHANGELOG.md the "Releases" and "Bugfixes" sub-sections under the ${VERSION} section.
       3. Paste the two sub-sections into the field.
       4. Change the level of the sub-headings from three hash marks (###) to two (##).
    5. Attach the newly build fat jar to the page. Use the part of the page that says "Attach binaries by dropping them here or selecting them." You want to do that.
    6. If this is a pre-release (some beta version or an explicit rc version) check the box for that.
    7. Click the "Publish release" button.
11. Checkout the dev branch.
12. Merge the changes into dev. 
    1. If the release was made from a release candidate branch, merge that branch into dev. 
       1. If it is not possible to fast-forward merge dev (i.e. if there have been commits on dev since the release candidate branch was made) then perform a non-fast-forward merge of the release candidate branch into dev. Use the commit message "Merging changes from version ${VERSION}". Skip the next step (do not merge master into dev).
       2. If it is possible to fast-forward merge dev (i.e. if there have been no commits on dev since the release candidate branch was made) then fast-forward merge the release candidate branch into dev and proceed to the next step (merge master into dev). 
    2. If the release was made from dev, simply merge master into dev. This will be a fast-forward merge, and dev and master will point to the same commit.
    3. There are other possible things you could do here. Maybe you made the release branch by cherry-picking commits from dev. In that case maybe rebasing dev onto master would be the most appropriate thing to do. I don't know, use your best judgment.
13. Make a commit to dev containing the following changes:
    1. In build.gradle find the line that begins with "version". Increment the version number (we will refer to this value later as ${NEW_VERSION}). Add "-SNAPSHOT" to the end of the version identifier.
    2. In CHANGELOG.md, add a new heading (with two # marks) for ${NEW_VERSION}. Below the heading, add the text "Not yet released." Add sub-headings (with three # marks) for "Features" and "Bugfixes". 
    3. The commit message should be "Bump version to ${NEW_VERSION}".
14. Push the dev branch.
15. Send an email out to the xnat_discussion board announcing the release.