Document toolboxDocument toolbox

Branching and Tagging

Owned by Mike Kellen (Unlicensed)
Last updated: Mar 09, 2012 by Xavier Schildwachter

Note, as of 12/7/2011 we have decided not to use tagging or releases.  The verbiage around those activites has been stricken below.

Notes on deployment policies

  • Major version number will remain 0 until we make a "marketing" decision that we are calling Synapse production instead of under development. Minor version number will correspond to Sprint number.
  • Code should never be deployed to any production system on Amazon directly from a development environment build.  Neither should you ever do a maven deploy directly from a development environment.  All deployed artifacts should be produced by a successful Bamboo build and deployed to Artifactory by that build process.  Only deploy artifacts to AWS that have been obtained from Artifactory. 
  • Code from the tip of trunk or a release branch will always have a maven version of 0.x-SNAPSHOT where x is the sprint (minor version) number.  Snapshots are stored in libs-snapshots-local/org/sagebionetworks/<path-to-artifact>.  Note that every successful Bamboo build overwrites artifactory's snapshots location, so this artifact is volatile.  However, Maven does put the SVN version number in the manifest of the .jars and .wars it builds, and our deployment tool pulls out the build number and puts it in the name of the versions it deploys to beanstalk, so it is always possible to find the build number of deployed code and determine whether a specific check-in occurred before or after deployment.
  • Trunk plus active release branches should have a Bamboo build watching them and building on every check-in. 
  • For weekly dev-team integration deployments to staging, it's not necessary to create a new tag.  We will simply deploy snapshots off trunk, and include the svn build number in the version label when deploying to Beanstalk.  Any deployments to customer-facing stacks should be tagged in SVN and archived in Artifactory.  This is done by giving creating a tag in SVN and checking in poms with a version number of 0.x.y, where y is incremented every time we want to snapshot a build. Artifacts for numbered releases are stored in Artifactory in libs-releases-local/org/sagebionetworks/<path-to-artifact>.  Note that the branching and tagging patterns described below are designed so that we never overwrite numbered versions in Artifactory after they are generated, and consequently we have archived versions of all the code that we have deployed already built that we can roll back to earlier versions quickly when needed.

Creating a Tag off Trunk

As we work in trunk, we will periodically want to tag and deploy builds of Synapse.  Assume we are starting with trunk labeled Synapse-0.x-SNAPSHOT.  The procedure is:

  1. Verify with platform team that all required code changes are checked in, and that nobody has any check-in that cause temporary stability issues (this latter case should normally be done in a development branch and merged into trunk when stable.  This lets us always quickly deploy out of trunk if we need to.)
  2. Verify that most recent check-in results in a clean Bamboo build of trunk
  3. Do a svn copy of trunk to tags/Synapse-0.x.y, where y is one higher than previous number, or zero if first release of a sprint. 
  4. Reconfigure the Bamboo build of trunk (the "Repository Path" field under "Configuration") to point to tags/Synapse-0.x.y.
  5. Check out tags/Synapse-0.x.y, then:
    1. edit  tools/SynapseDeployer/pomVersioner.py so that oldVersion=0.x-SNAPSHOT, newVersion=0.x.y, and startPath 'points' to your local copy, then run pomVersioner.py. 
    2. Validate that changes to poms and any version info in R client makes sense
    3. Check this into SVN.  Eclipse will give you a warning that you shouldn't be checking in to a tag.  Do it anyway.
  6. Bamboo should now run a clean build of the tag, which will end up as a permanent versioned artifact in artifactory.
  7. Reconfigure the Bamboo build to point back to trunk
  8. Delete the tag code from your workspace so you never accidentally modify the tagged version again.
  9. Clean labeled artifacts are sitting in artifactory libs-releases-local/org/sagebionetworks/<path-to-artifact>/0.x.y

Creating a Branch at the end of a Sprint

For end of sprint x, the branching and tagging procedure is:

  1. Send email to platform declaring a check-in freeze on trunk
  2. Verify that most recent check-in results in a clean Bamboo build of trunk
  3. Do a svn copy of trunk to branches/Synapse-0.x.  If we need to do work to create a patch release, it will go in this branch, and continue to be labeled 0.x-SNAPSHOT.
  4. Do a svn copy of branches/Synapse-0.x to tags/Synapse-0.x.y.  y is one higher than previous number, or zero if first release of a sprint.
  5. Check out tags/Synapse-0.x.y, then:
    1. edit  tools/SynapseDeployer/pomVersioner.py so that oldVersion=0.x-SNAPSHOT, newVersion=0.x.y, and startPath 'points' to your local copy, then run pomVersioner.py. 
    2. Validate that changes to poms and any version info in R client makes sense
    3. Check this into SVN.  Eclipse will give you a warning that you shouldn't be checking in to a tag.  Do it anyway.
  6. Create a new Bamboo build called "Synapse-0.x" based on the existing Bamboo build of trunk and reconfigure it to point it at branches/Synapse-0.x
  7. Manually kick off a build, which should pass and create the 0.x artifacts in Artifactory
  8. Reconfigure the Bamboo build to point to branches/Synapse-0.x.  The next time somebody checks into the branch it should kick off this build.
  9. Run SynapseDeployer/pomVersioner.py to bring trunk up to minor version x+1.  This should generate a bamboo build of trunk that pushes 0.[x+1]-SNAPSHOT to Artifactory for the first time.  Verify that this in fact happens.
  10. Send email to platform declaring trunk and branch open for check-ins.  The end of sprint build is sitting in artifactory libs-releases-local/org/sagebionetworks/<path-to-artifact>/0.x.y

Creating a Patch Release on a Release Branch

Once we have moved trunk up to Synapse-0.x, we may find situations where we want to deploy bug fixes to production on the x-1 branch to avoid deploying other code in trunk before it is ready.  In this case

  1. Developers are responsible for down-merging patches to the branch from trunk (or vice versa as appropriate).
  2. Verify that the most recent check-in on the branch resulted in a clean Bamboo build, and verify with the developer who created the patch that it is in fact checked in.
  3. Do a svn copy of branches/Synapse-0.x to tags/Synapse-0.x.y
  4. Reconfigure the Bamboo build of the branch (the "Repository Path" field under "Configuration") to point to tags/Synapse-0.x.y.
  5. Check out tags/Synapse-0.x.y, then:
    1. edit  tools/SynapseDeployer/pomVersioner.py so that oldVersion=0.x-SNAPSHOT, newVersion=0.x.y, and startPath 'points' to your local copy, then run pomVersioner.py. 
    2. Validate that changes to poms and any version info in R client makes sense
    3. Check this into SVN.  Eclipse will give you a warning that you shouldn't be checking in to a tag.  Do it anyway.
  6. Bamboo should now run a clean build of the tag, which will end up as a permanent versioned artifact in artifactory.
  7. Reconfigure the Bamboo build to point back to the branch
  8. Delete the tag code from your workspace so you never accidentally modify the tagged version again.
  9. Clean labeled artifacts are sitting in artifactory libs-releases-local/org/sagebionetworks/<path-to-artifact>/0.x.y