RELEASE_PROCESS.md

Compose release process

To get started with a new release

1. Create a bump-$VERSION branch off master:

   git checkout -b bump-$VERSION master
   

2. Merge in the release branch on the upstream repo, discarding its tree entirely:

   git fetch origin
   git merge --strategy=ours origin/release
   

3. Update the version in docs/install.md and compose/__init__.py.

   If the next release will be an RC, append rcN, e.g. 1.4.0rc1.

4. Write release notes in CHANGES.md.

5. Add a bump commit:

   git commit -am "Bump $VERSION"

6. Push the bump branch to your fork:

   git push --set-upstream $USERNAME bump-$VERSION

7. Open a PR from the bump branch against the release branch on the upstream repo, not against master.

When a PR is merged into master that we want in the release

1. Check out the bump branch:

   git checkout bump-$VERSION
   

2. Cherry-pick the merge commit, fixing any conflicts if necessary:

   git cherry-pick -xm1 $MERGE_COMMIT_HASH

3. Add a signoff (it’s missing from merge commits):

   git commit --amend --signoff
   

4. Move the bump commit back to the tip of the branch:

   git rebase --interactive $PARENT_OF_BUMP_COMMIT
   

5. Force-push the bump branch to your fork:

   git push --force $USERNAME bump-$VERSION
   

To release a version (whether RC or stable)

1. Check that CI is passing on the bump PR.

2. Check out the bump branch:

   git checkout bump-$VERSION
   

3. Build the Linux binary:

   script/build-linux
   

4. Build the Mac binary in a Mountain Lion VM:

   script/prepare-osx
   script/build-osx
   

5. Test the binaries and/or get some other people to test them.

6. Create a tag:

   TAG=$VERSION # or $VERSION-rcN, if it's an RC
   git tag $TAG
   

7. Push the tag to the upstream repo:

   git push git@github.com:docker/compose.git $TAG
   

8. Create a release from the tag on GitHub.

9. Paste in installation instructions and release notes.

10. Attach the binaries.

11. Don’t publish it just yet!

12. Upload the latest version to PyPi:

    python setup.py sdist upload
    

13. Check that the pip package installs and runs (best done in a virtualenv):

    pip install -U docker-compose==$TAG
    docker-compose version
    

14. Publish the release on GitHub.

15. Check that both binaries download (following the install instructions) and run.

16. Email maintainers@dockerproject.org and engineering@docker.com about the new release.

If it’s a stable release (not an RC)

1. Merge the bump PR.

2. Make sure origin/release is updated locally:

    git fetch origin
   

3. Update the docs branch on the upstream repo:

    git push git@github.com:docker/compose.git origin/release:docs
   

4. Let the docs team know that it’s been updated so they can publish it.

5. Close the release’s milestone.

If it’s a minor release (1.x.0), rather than a patch release (1.x.y)

1. Open a PR against master to:

   • update CHANGELOG.md to bring it in line with release
   • bump the version in compose/__init__.py to the next minor version number with dev appended. For example, if you just released 1.4.0, update it to 1.5.0dev.

2. Get the PR merged.

Finally

1. Celebrate however you’d like.

This is looking great! I have a couple of questions:

• Write release notes in CHANGES.md.

How do we do that? Do we detail every PR or do you use your judgement and pick only "highlights"

• 8. Create a release from the tag on GitHub.

I'm afraid I don't understand what this means. We've pushed a branch with the release tag to GitHub, so what does create a release mean, is it the build binaries step again?

• 9. Paste in installation instructions and release notes.

Which installation instructions? Do we generate new instructions for each release or are we copying this file compose/docs/install.md? Sorry if this is a stupid question :/