We’ve gotten great feedback from our users on our releases. We realize that while making frequent releases helps our users get access to new features and bug fixes, these can also introduce unpredictable breaking changes. We have worked to put a system in place that is flexible but has a rigorous and predictable schedule.
However, it is hard to achieve that with typical semantic versioning. Even a small API breaking change requires a major version increase, while a very large feature affecting the way data is laid out on disk but containing no API changes, would be considered a minor release. It goes to say that in over 4 years of Dgraph, there has only been one major release, which doesn’t do justice to all the work that has gone into the system. At the same time, our v2.0 release has led to a rush of cramming in all possible breaking changes to avoid another major version release within a few months, which delays the release process and makes it hard to do testing.
Learning from this and starting with the next release, Dgraph releases are going to have date-based versioning, known as Calendar Versioning or CalVer. That means, Dgraph would be released at a regular, pre-determined cadence (3 times a year). Each release would be considered a major release. This system is flexible because we will not hold our release for new features that are not completely ready yet. It is also predictable because by looking at a release version, a user can judge when it was released and when it would reach its end of life. This versioning scheme is most prominently used by Ubuntu.
Our release scheme will be YY.MM.PatchNumber for major releases and YY.MM.0-beta.MMMDD for beta releases of a future release.
YY : Short year which indicates which year the release was made GA.
MM : Zero padded month indicating the month that the release was made GA. We will have major releases every four months: (March, July, November) or (03, 07, 11). These releases will have bug fixes and new features with the possibility of breaking changes. We will provide scripts and tools to make upgrades easier between these versions.
PatchNumber : Patch releases are focused on bug fixes and are backward compatible. If a bug fix has a breaking change it will not be released till the next major release but will be available as a beta.
Beta Releases: Beta releases are available before the GA and are cut from the release branch, which will be in sync with Master. Their naming scheme contains the release the beta is destined for (YY.MM.0-beta.MMMDD), and the date that the beta was made available (YY.MM.0-betaMMMDD). Before GA we will have a period of code freeze on the release branch and then we will make the release GA. This is done to make sure we are releasing a high quality and stable product. After the release is GA, every new feature will then go to the next release branch. It is up to Dgraph team to decide when to do a beta release, we will aim to do a beta release every time we are ready with a new feature.
End Of Life Policy: We will support the release series for one year and security patches for 18 months. For example, release series (20.03.x) will be supported until March 2021 with security patches until September 2021.
User Facing Libraries: It is our intention to keep things as simple as possible, so in March we are going to sync all of our user facing libraries with Dgraph release. So along with March Dgraph release, we will also release all clients (dgo, dgraph4j,….) with the same release number as Dgraph. For releases after March, we will release any client that has a breaking change and will sync its release number with Dgraph. So at any given time, the client’s release number will be in sync with the earliest compatible Dgraph version.
Example : We will have our first CalVer release in March. The version for March GA release will be: 20.03.0 . Later we will release a patch with bug fixes and no breaking changes: 20.03.01 . Let’s say it is June 15th and we are ready with a new feature or a bug fix that has breaking changes. Since it is not July yet, we will release a beta from the release branch: 20.07.0-beta.Jun15 . On the July release date, we will make the July GA release: 20.07.0 .
In March, all client versions would be set to 20.03.0. If the July release only breaks a particular client, we will only release that client. In this case the Dgraph version will be 20.07.0 that has client-api changes, then the client library version will be 20.07.0. Any client libraries not affected will remain as 20.03.0 (because they are still compatible with the March release).
For client-versioning, there’s a special exception for the Go client dgo: dgo versions would be called v200.03.0, v201.07.0, v202.11.0 if there are breaking API changes within the year (the last number in the major version increments). This versioning scheme is still calendar versioned yet supports the tooling for Go Modules where the major version dictates how the Go toolchain manages dependency updates.
Hope this versioning scheme is clear and makes sense to all our users. This scheme makes it much easier for us to ensure that we keep releasing Dgraph regularly, while also communicating to our users about client/server compatibility, our maintenance policy and when it is time to upgrade.
Let us know if you have any questions or comments!
