LORE Release Workflow

Quick Start


These instructions presume you’re releasing LORE version 0.10.0.

git fetch
git checkout master
git pull
git flow release start 0.10.0
vi lore/settings.py # change version number
git-release-notes v0.9.0..master util/release_notes_rst.ejs
vi RELEASE.rst # paste results of prior command at top of file, updating the release number
git add RELEASE.rst lore/settings.py
git commit -m "Release 0.10.0"
git flow release publish 0.10.0
# Verify that the Travis-ci build succeeds
git-release-notes v0.9.0..master util/release_notes.ejs
# Create PR on the ``release-candidate`` branch named ``rc/0.10.0`` (The
# PR description isn't important)
# Merge this PR immediately to kick off the build
# Create PR on the ``release`` branch named ``rc/0.10.0`` using the
# console output from git-release-notes v0.9.0..master util/release_notes.ejs
# as the PR description
# Once the ``release`` branch deploys on https://lore-rc.herokuapp.com ,
# Instruct developers to view the ``release`` branch PR description and
# validate their commits on https://lore-rc.herokuapp.com
# Wait for all checkboxes to be checked
# Check with Dev-Ops buddy whether migrations need to be run for this release
git flow release finish 0.10.0
git push --tags
# Send release notification to LORE mailing list - [email protected]

Detailed Instructions

Create, commit, and push release candidate branch

git fetch
git checkout master
git pull
git flow release start 0.10.0

Update the VERSION number in lore/settings.py following Semantic numbering practice.

vi lore/settings.py # change version number

Generate the release notes in reStructuredText format:

git-release-notes v0.9.0..master util/release_notes_rst.ejs

Update release.rst with this version’s release notes (the console output generated by running release_notes_rst.ejs). Edit the new release notes to correct the release number, make each statement in the past tense, capitalize the first word, and end sentences with a period.

vi RELEASE.rst

Add, commit, and push the two files you have updated to publish the release.

git add RELEASE.rst lore/settings.py
git commit -m "Release 0.10.0"
git flow release publish 0.10.0

The “release publish” (push) will trigger a build on Travis CI. https://travis-ci.org/mitodl/lore/builds For each commit throughout the release, it’s good practice to check that the build succeeded before proceeding.

Create Pull Requests

Developers will start their verification tests as soon as they learn that you’ve created the PR with the checkboxes. Since the deployment to lore-rc can take a while, merge the release-candidate branch PR as soon as you create it to move its deployment off the critical path.

Make three PRs based on the release branch you just published:

  • One to the release-candidate branch named rc/0.10.0
  • Merge this PR immediately to kick off the build.
  • One to the release branch named rc/0.10.0 containing a checklist of commits
  • one to the master branch named Release 0.10.0

Run git-release-notes with the other template to create the Pull Request descriptions for the release branch.

git-release-notes v0.9.0..master util/release_notes.ejs

and paste the Markdown output as the description of the PR to the release branch rc/0.10.0 (This is the one with the checkboxes.)

Tell developers to test their changes on the LORE release candidate server, http://lore-rc.herokuapp.com and then bug team members until all the check boxes are checked.

Finish the release

When all the boxes are checked finish the release.

git flow release finish 0.10.0
git push --tags

Follow this by merging the remaining PRs and sending a release notice to LORE users.

The email address of the LORE mailing list we use for release notification is odl-lore-announce@mit.edu It is a mailman list located here: https://mailman.mit.edu:444/mailman/admin/odl-lore-announce/general The list is set to hold all emails for review by list moderators who are notified by email when an email is received.

Release Process Roles

the important piece for the dev-ops person is migrations so the devops person should actually do the merge to release so they can run migrations before they do so which means we are almost exactly following the edX release strategy, where there is a release master and “dev-ops buddy”.


Create the release notes with a utility called git-release-notes. https://www.npmjs.com/package/git-release-notes Its output is written to the console.

git-release-notes takes two command line arguments. The first argument takes a range of git references to determine which commits to include in the release. In the example given it is all commits from the last release to what is in master.

The second command argument specifies a template to format the output. LORE has two templates.

  • util/release_notes_rst.ejs formats the output as reStructuredText for inclusion in RELEASE.rst.
  • util/release_notes.ejs formats the output as Markdown so as to precede each commit with a checkbox, and follow each with a link to the developer’s commit history. Add these release notes as the description for the GitHub PR to the release branch.


The LORE project uses a different branch naming scheme than is the Git-Flow default. The easiest way to configure this alternate scheme is to add this block to your ~/.gitconfig file.

[gitflow "branch"]
    master = release
    develop = master
[gitflow "prefix"]
    feature = feature/
    release = rc/
    hotfix = hotfix/
    support = support/
    versiontag = v