Release notes

Adding release notes to your GitHub repo makes it very easy to see what the current state of the code is at any given time on production servers. Web, iOS, and Android developers with GitHub access can review release notes easily. Additionally, you can generate a PDF to share with product owners or other project management staff, or copy and paste them to a document on Basecamp.

You should add release notes whenever you deploy code to production. You'll find that it only adds about 5–10 minutes to the typical deploy process.

Adding release notes

In your GitHub repo, simply click on "Releases", and click the button to "Draft new release". From the dropdown menu, choose a commit, then assign a tag that conforms to semantic versioning standards (e.g., v1.0.2). Give the release a title and add notes in Markdown format.

The notes should generally have a bulleted list under one or more of the following headers: "New", "Improved", and "Fixed". Any new features added since the last deploy should be listed under "New". Any existing features that have been updated or changed should be listed under "Improved". And, any bugs that have been fixed should be listed under "Fixed". Whenever possible, link to relevant JIRA stories, particularly for bugs. It's also helpful to finally note who deployed the code and when.

Here is a sample format:

### New
- List new features here
- Perhaps there's more than one

### Improved
- Better error messages
- Tokens expire after 60 days instead of 30

### Fixed
- Fixed the problem with duplicate data ([JIRA-302](https://jira.com/project/302))


Deployed on 2016-01-04 by @foresmac.

Tagging older commits

If you neglect to add notes during release, or several pull requests have been merged and you can't access the specific commit from the dropdown menu, you can easily tag the older commit and use GitHub's UI to "Add Release Notes" to that tag. You just need a couple commands in your terminal to mark it with the correct date:

# Set the HEAD to the old commit that we want to tag
git checkout 9fceb02

# temporarily set the date to the date of the HEAD commit, and add the tag
GIT_COMMITTER_DATE="$(git show --format=%aD | head -1)" git tag -a v1.2 -m "Some useful message"

# set HEAD back to whatever you want it to be
git checkout master

# Push the tags to vokal master; requires push/merge access to the repo
git push --tags vokal master