Creating a New Release

POCS follows a branching scheme wherein bug fixes and development of new features takes place on the develop branch and where periodic releases are done to the master branch. This document describes the process of creating an official versioned release.

Step One: Create release branch off develop

From the develop branch, create a new branch with a name that reflects the new version number. For a version v0.5.1 release:

(panoptes-env) $ git checkout -b release-0.5.1 develop

Step Two: Update metadata for release

Modify the actual version

Version information is kept in the $POCS/pocs/version.py file and follows a semantic version scheme. For the most part this means that there will be "patches" to each "minor" release. A "major" release usually signifies a change that is not backwards-compatible or is otherwise large in scope. The format is MAJOR.MINOR.PATCH.

Update the Changelog

We want to keep the Changelog up to date with the release so major changes should be outlined in a user legible way according to this format. There is an "Unrelease" section at the top of the file which should be kept up to date with any changes as they are merged into develop, so doing a release should be just a matter of filling out the version number and date. From the above url:

A good change log sticks to these principles:

• It’s made for humans, not machines, so legibility is crucial.
• Easy to link to any section (hence Markdown over plain text).
• One sub-section per version.
• List releases in reverse-chronological order (newest on top).
• Write all dates in YYYY-MM-DD format. (Example: 2012-06-02 for June 2nd, 2012.) It’s international, sensible, and language-independent. [Use the current UTC date_]
• Explicitly mention whether the project follows Semantic Versioning.
• Each version should:
  • List its release date in the above format.
  • Group changes to describe their impact on the project, as follows:
    • Added for new features.
    • Changed for changes in existing functionality.
    • Deprecated for once-stable features removed in upcoming releases.
    • Removed for deprecated features removed in this release.
    • Fixed for any bug fixes.
    • Security to invite users to upgrade in case of vulnerabilities.

Step Three: Commit the file and create a pull request against master

Give the commit a simple commit message that indicates the new version name. There is no need to duplicate the changelog information in the commit message.

Create a pull request against master via github. The master branch is locked and requires review by someone else before it can be accepted. Request that the team panoptes/pocs-developers review the pull request and it will notify the team.

Step Four: Merge the pull request

Note: This step is done after the above three steps and may or may not be performed by the same individual. Whoever merges the pull request (this step) should also complete the steps below.

After the pull request has passed all tests and has been reviewed it should be merged via github via the "Create a merge commit" option (which is not the default!).

Github should give you the option to delete the release branch on panoptes/POCS. It is okay to delete the branch but make note of the following step, which requires the branch to still exist in your fork.

Step Five: Merge release changes back into develop

The release branch has a number of changes from develop. At a minimum this will include the difference in version number and changelog as described above but may also include other commits needed for the release. These changes should be merged back into develop:

(panoptes-env) $ git checkout develop
(panoptes-env) $ git merge --no-ff release-0.5.1
(panoptes-env) $ git push origin develop

Since this will be in your fork of POCS you will then need to generate a pull request from yourname/POCS to panoptes/POCS, which will also need to be reviewed by another team member. It is okay to squash this commit.

After the release branch has successfully been merged into develop you are free to delete the release branch from your local fork and from panoptes/POCS (if not done in Step Four).

Step Six: Make a new release

Go to the Releases section on github and click the "Draft a new release" button. This will give you the option to create a new tag against a specific branch. Name the tag according to the release but with a v appended, e.g. v0.5.1 and make sure you are tagging the master branch, which contains the newly merged code.

For now just put the release version into the "Release title" field and copy the new items in Changelog into the "Describe" field.

Step Seven: Notify other members

For now just send a message to the general and developers channel in Slack.

Congratulations, you've made a new release!