Release Process for sbt-site

Branch Management

This project uses GitFlow for branch management. This means that PRs should be merged onto develop, not master. New releases are prepared from a release/vX.Y.Z branch, and master is only updated from release/... branches (there are also hotfix branches, but they aren’t common).

An easy way to use GitFlow is to make use of the support built-in to the SourceTree frontend which includes support for GitFlow. The images below are taken from SourceTree. There are other ways to use GitFlow if you don’t want to use SourceTree.


  1. Make sure you have BinTray credentials for the “sbt” organization. You won’t be able to publish without them.
  2. Make sure the working directory is clean and up-to-date with the remote, and the tests pass (e.g. sbt scripted). Some people like to run git clean -fdx.
  3. Start the release branch process:

    Give the release branch a version name with the form v<X>.<Y>.<Z>:

    You should now be on the release branch:
  4. Create the file src/main/paradox/notes/<X>.<Y>.<Z>.md. Sometimes this file already exists if PR submitters are super awesome. Go through the commit logs and collect the major new features, bug fixes, deprecations, and anything else relevant to users. Making note of breaking changes is particularly important. See previous release notes for format/content conventions.
  5. Edit the version setting in build.sbt to match "<X>.<Y>.<Z>"
  6. Commit your current changes onto the release branch.
  7. Run sbt bintrayWhoami to confirm your publishing credentials are set up. See sbt documentation on how to get set up with Bintray.
  8. Run sbt ^publish to build the packages and stage artifacts on Bintray.
  9. Confirm the plugin is properly staged for release on Bintray. You should see a message that looks looks like this:
  10. Run sbt ^bintrayRelease. This moves the plugin from the staged release to published release on Bintray.
  11. Finish release per GitFlow process:

    Accept the defaults:

    GitFlow will merge release onto master and develop, and switch the current branch to develop.
    You must push changes yourself to both develop and master.
  12. Create a release entry in GitHub. Because GitFlow automatically adds a tag to the history, GitHub picks it up as a release…
    …but we have to copy the release notes from our src/main/paradox/notes/<X>.<Y>.<Z>.md file manually.
  13. Monitor the TravicCI build and make sure it updates the manual with the latest version.
  14. Announce release using herald. Also announce release on Twitter, including #scala and @scala_sbt and major contributor handles (if available). Provide a link to the GitHub release page in tweet.
  15. Announce on #sbt-site and #sbt-dev Gitter channels.
  16. Important: On the develop branch, edit the version setting in build.sbt to match "<X>.<Y+1>.0-SNAPSHOT". Commit and push.