===================== LORE Release Workflow ===================== Quick Start ----------- prerequisites: - ``git-release-notes`` - https://www.npmjs.com/package/git-release-notes - ``git-flow`` - https://github.com/nvie/gitflow - You've configured Git-Flow to use LORE branch naming scheme. (See Git-Flow_ section below) These instructions presume you're releasing LORE version 0.10.0. .. code-block:: bash 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 - odl-lore-announce@mit.edu Detailed Instructions ---------------------- Create, commit, and push release candidate branch ================================================= .. code-block:: bash 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. .. code-block:: bash vi lore/settings.py # change version number Generate the `release notes`_ in reStructuredText format: .. code-block:: bash 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. .. code-block:: bash vi RELEASE.rst Add, commit, and push the two files you have updated to publish the release. .. code-block:: bash 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. .. code-block:: bash 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. .. code-block:: bash 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". .. _release notes: ``git-release-notes`` ===================== 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. .. _Git-Flow: Git-Flow ======== 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. .. code-block:: bash [gitflow "branch"] master = release develop = master [gitflow "prefix"] feature = feature/ release = rc/ hotfix = hotfix/ support = support/ versiontag = v