Legacy Driver Release Guide

If you're reading this, chances are you're about to issue a release for a new version of the legacy C++ driver. Congratulations!

Before Getting Started

To perform the release process, you will need the following:

• git, python, doxygen installed on your local machine.
• Push access to the mongodb/mongo-cxx-driver repository on GitHub.
• Push access to the 10gen/apidocs repository on GitHub.
• Administrative access on the C++ Driver JIRA project.

This guide assumes that you have a local clone of the mongo-cxx-driver and apidocs repositories, and that your GitHub remote is configured with remote name origin.

In addition, this guide assumes that you are about to issue a production release named legacy-x.y.z. The process for issuing a release candidate is nearly identical, with two exceptions:

• The new version string will be in format legacy-x.y.z-rcw, instead of legacy-x.y.z. In this guide, replace all instances of the latter with the former.
• The copy for the release notes and announcement will need to indicate that the release is not for production use.

Lastly, this guide also assumes that the following release is is named legacy-x.y.(z+1). The name of the following release may differ from this.

Confirm All Outstanding Issues Resolved in JIRA

• On the project roadmap panel in JIRA, ensure that all tickets marked for legacy-x.y.z are resolved. Assuming there are 10 issues in the release, you should see the text "10 of 10 issues have been resolved" on this page.

Create and Push the BUMP Commit

• Change directories to your local clone of mongo-cxx-driver, and use git status to confirm a clean working tree, and that you have the legacy branch checked out.

• Make edits to the following files. You will be changing the development version string (legacy-x.y.z-rcw-pre) in these files to the release version string (legacy-x.y.z):

  • SConstruct: update value of mongoclientVersion.
  • etc/doxygen/config: update value of PROJECT_NUMBER.

• Commit and push the bump commit, as follows:

   git add SConstruct etc/doxygen/config
   git commit -m "BUMP legacy-x.y.z"
   git push origin legacy
  

Pushing the BUMP commit to the origin will kick off builds in Evergreen, Travis CI and AppVeyor. Wait for all three builds to finish and pass.

Tag the Release

• From the same directory, create and push a tag for the commit that will serve as the release.

   git tag legacy-x.y.z
   git push origin legacy-x.y.z
  

Generate and Publish Documentation

• In your local clone of the apidocs repo, build and publish the release documentation as follows. The build.py script will modify existing files, and also create files in a new directory named cxx/legacy-x.y.z.

   python build.py cxx
   git add cxx/
   git add -u
   git commit -m "Documentation for C++ driver release legacy-x.y.z"
   git push origin master
  

Within an hour, a regularly scheduled task will automatically deploy the new documentation at the legacy C++ driver API documentation page.

Bulk Transition All Tickets Targeted for Release to "Closed"

• Re-visit the project roadmap panel in JIRA.
• Under the legacy-x.y.z version, click the link "X issues" on the left-hand side. This will bring you to the search page that displays all tickets targeted for the version about to be released.
• Select "Tools => Bulk Change" from the upper-right hand corner of the search page.
• In the "Choose Issues" dialog, select all issues.
• In the "Choose Operation" dialog, select "Transition Issues".
• In the "Edit Fields" dialog, click "Next" without modifying any fields.
• Confirm the change.

Release the Version in JIRA

• Visit the versions administrative panel in JIRA.
• Hover over the version to be released. A cog icon will appear on the right-hand side of the page.
• Click the cog icon, and select "Release" from the drop-down. A pop-up will appear, and it should contain no warnings about unresolved issues.
• Set "Release date" to the current date.
• Confirm the release.

Create the Next Version in JIRA

• From the versions administrative panel, determine whether or not the version corresponding to the next release already exists.
• If the version already exists, continue to the next step.
• If the version does not exist, enter the new version's Name and Description at the prompt towards the top of the page. Select the current date as the next version's start date, and pick a release date. Typically, the legacy C++ driver is released only a small handful of times each year, so the release date for the new version should likely be at least a couple of months out (barring extraordinary circum