Upcoming Changes to the MongoDB C++ Driver



By Andrew Morrow, Kernel Engineer at MongoDB

In coordination with the upcoming MongoDB 2.6 release, the Kernel team is changing how the MongoDB C++ driver is developed, licensed, released, and distributed.

What are we doing?

As of MongoDB 2.6.0-rc1, it will no longer be possible to build the C++ driver from the MongoDB server sources. The files required to build the driver have been forked to a new repository on GitHub, and will be maintained independently of the server sources.

Can I start using it now?

Yes. We are still fixing up some post-fork rough edges though, so please consider the current state of the new repository to be unstable. We should be announcing release candidates soon. Release candidates are useable for testing, but should not be used in production.

Why are we doing this?

By separating the development streams for the server and the C++ driver we will be able to respond to C++ driver issues without being tied to the server release schedule, as well as make changes that were previously difficult to apply in the context of the server repository. We want to make developing and using the C++ driver a better experience for everyone involved.

How will the new driver be versioned?

The new repository will initially offer two release streams: the ‘26compat’ release stream, and the 'legacy’ release stream.

The '26compat’ branch and release stream will contain a minimally altered snapshot of the C++ driver files from the server repository as of MongoDB 2.6.0-rc0. It is intended to be a drop-in replacement for existing users of the C++ driver seeking minimal disruption to their current workflow and code. The build system, physical structure, C++ API, and other aspects of the driver will change minimally in this stream. We will backport selected fixes from the v2.6 server repository branch as needed, but conservatively. Enhancements and improvements will be minimal or non-existent.

The 'legacy’ branch and release stream will more aggressively diverge from the server sources. While this release stream will retain the overall look and feel of the existing driver, we are likely to make small breaking changes to the physical structure, build system, API, and testing model for the driver. New driver features will only be made in this release stream. Our goal in this release stream is to provide meaningful improvements to the C++ driver, while requiring only modest changes on the part of users.

I see a ‘legacy’ branch in the new repository, but no ‘26compat’ branch. Why?

The initial release candidates for the 26compat release stream will be made from the ‘legacy’ branch. When MongoDB 2.6.0 is released, the 26compat branch will be forked from the legacy branch to track the MongoDB 2.6 point releases. Until that split, the legacy branch is effectively the 26compat branch. After the 26compat branch is formed, the legacy branch will begin to receive improvements and changes that are not compatible with the goals of the 26compat branch.

What license will apply to the C++ drivers in this repository?

Unlike the driver embedded within the server repository, which is a mix of Affero GPL and Apache 2.0 licensed files, all files in the new repository will be Apache 2.0 licensed.

How will existing users of the C++ driver be affected?

Our aim is to minimize disruption, but also to enable more rapid evolution and improvement of the driver. Since these goals are in conflict, there will be a period where there are several valid ways to obtain and build the C++ driver, all yielding slightly different results. We will be updating the documentation to reflect these alternatives in more detail, but as an overview, the initial options are to:

  1. Switch to the new C++ driver repository and use the 26compat release stream. This should offer as close to a drop-in replacement for your existing workflow and application code as can be managed. Your help in testing the release candidates of this release stream will help us ensure that our first production release of this stream is an effective replacement for the older mechanisms of obtaining the driver.
  2. Continue to use the server repository build of the driver. This process is valid for releases of the driver up to and including 2.6.0-rc0, but will not advance beyond that release. If you are using this process and wish to continue with minimal change, we encourage you to move to the 26compat stream.
  3. Continue to use the tarball versions of the driver. This process will remain valid for releases of the driver up to and including 2.5.2, but will not advance beyond that release. If you are using the C++ Client Driver tarball, we strongly encourage you to move to any of the other processes listed above.

Later, once the 26compat stream has been stabilized, there will be an additional option to track the legacy release stream. Our goal is that all C++ driver users will eventually be able to migrate to the legacy release stream.

What about JIRA, SERVER tickets, etc.?

There is a new JIRA project for the C++ driver: https://jira.mongodb.org/browse/CXX. We will be evaluating existing SERVER tickets filed under the “C++ Driver” component or label and migrating or copying them to the new project as appropriate.

New C++ driver issues should be filed in the CXX project.

Why is it called the 'legacy’ driver or the 'legacy’ branch?

We are saving the master branch of the repository for something new and exciting a bit further down the road. In the meantime, we want to make the experience with the existing C++ driver better, but it isn’t going to diverge radically from the 'legacy’ of its origins in the server codebase.

Can I help?

Absolutely. We are very interested in feedback on the plan outlined above, and your feedback will help us solidify the details. We will be releasing an RC of the 26compat release stream sometime in the next week or two, and testing of that release candidate will be much appreciated.

Similarly, we will be releasing a series of unstable releases of the legacy driver leading to a stabilized version in the near future. Experimenting with these releases will give us the best opportunity to improve the driver for the community.

I have other questions…

Please post to the mongodb-user or mongodb-dev mailing lists with any questions about this announcement and the C++ Driver team will be happy to answer.

Thank You,

The C++ Driver Team