From 33b87e0784d6c6d15a2c343513f73b2b7fa34ee1 Mon Sep 17 00:00:00 2001 From: Alexander Laye Date: Tue, 29 Sep 2026 17:06:31 -0400 Subject: [PATCH 1/4] add new blog post for versioning --- blogs/_posts/2026-09-29-versioning.md | 34 +++++++++++++++++++++++++++ 1 file changed, 34 insertions(+) create mode 100644 blogs/_posts/2026-09-29-versioning.md diff --git a/blogs/_posts/2026-09-29-versioning.md b/blogs/_posts/2026-09-29-versioning.md new file mode 100644 index 0000000..d856675 --- /dev/null +++ b/blogs/_posts/2026-09-29-versioning.md @@ -0,0 +1,34 @@ +--- +title: "DocumentDB Version Standards for 1.0 and Beyond" +description: A guide to how we update DocumentDB and the standards for future updates. +date: 2026-09-29 +featured: true +author: DocumentDB team +category: documentdb-blog +tags: + - DocumentDB + - "1.0" + - Release + - Version +--- +Now that DocumentDB is releasing its 1.0 version, it is important to clarify what exactly a major version bump means, and how we plan on moving forward with version changes. In brief, major versions will release every year, and we will support each major release until three months after the next major comes out. Minor releases will continue to update on a roll-forward basis. + +## Annual major releases + +DocumentDB will publish one new major version each year. The next major version is developed on `main`; supported major versions are maintained on branches such as `release/v3`. We will continue to build artifacts for the latest minor release alongside the supported major versions. + +When a new major version begins support, a release branch is created and artifacts are built. The previous major version then enters a three-month grace period before support ends. Security fixes will be backported to supported release branches, with new artifacts built until support ends. Other bug fixes will be backported case by case. + +## Release candidates + +Release candidates use the `-RC` suffix. For example, a release candidate for version 3 could be tagged `v3.0-RC1`, followed by a final release tag such as `v3.0-0`. After the final release, `release/v3` becomes the supported branch for version 3, while `main` moves on to development for version 4. The previous `release/v2` branch remains supported during its grace period. + +## What belongs in major, minor, and patch releases + +Major releases are only time-based. They happen yearly and will include instructions for updating from previous long-term supported major versions. That means that minor updates can include all breaking changes, such as removal of support for PostgreSQL dependencies, + +## Upgrade path + +DocumentDB will support direct in-place upgrades between consecutive major versions. There is also a simple path from the current major release to the latest minor release of that same major. This will allow for a simple switch from long-term support to the latest builds. + +Release candidates are different. Upgrades from release candidate versions will not be supported. Release candidates use the same extension version as the first full release for that major, so there is no reliable extension upgrade path from an RC to the final release. From 0b3b41f43bb513b1aff0de41514a273c2df4d8c1 Mon Sep 17 00:00:00 2001 From: Alexander Laye Date: Thu, 1 Oct 2026 09:05:54 -0400 Subject: [PATCH 2/4] shift focus to the two track explaination --- blogs/_posts/2026-09-29-versioning.md | 34 --------------------- blogs/_posts/2026-10-01-versioning.md | 44 +++++++++++++++++++++++++++ 2 files changed, 44 insertions(+), 34 deletions(-) delete mode 100644 blogs/_posts/2026-09-29-versioning.md create mode 100644 blogs/_posts/2026-10-01-versioning.md diff --git a/blogs/_posts/2026-09-29-versioning.md b/blogs/_posts/2026-09-29-versioning.md deleted file mode 100644 index d856675..0000000 --- a/blogs/_posts/2026-09-29-versioning.md +++ /dev/null @@ -1,34 +0,0 @@ ---- -title: "DocumentDB Version Standards for 1.0 and Beyond" -description: A guide to how we update DocumentDB and the standards for future updates. -date: 2026-09-29 -featured: true -author: DocumentDB team -category: documentdb-blog -tags: - - DocumentDB - - "1.0" - - Release - - Version ---- -Now that DocumentDB is releasing its 1.0 version, it is important to clarify what exactly a major version bump means, and how we plan on moving forward with version changes. In brief, major versions will release every year, and we will support each major release until three months after the next major comes out. Minor releases will continue to update on a roll-forward basis. - -## Annual major releases - -DocumentDB will publish one new major version each year. The next major version is developed on `main`; supported major versions are maintained on branches such as `release/v3`. We will continue to build artifacts for the latest minor release alongside the supported major versions. - -When a new major version begins support, a release branch is created and artifacts are built. The previous major version then enters a three-month grace period before support ends. Security fixes will be backported to supported release branches, with new artifacts built until support ends. Other bug fixes will be backported case by case. - -## Release candidates - -Release candidates use the `-RC` suffix. For example, a release candidate for version 3 could be tagged `v3.0-RC1`, followed by a final release tag such as `v3.0-0`. After the final release, `release/v3` becomes the supported branch for version 3, while `main` moves on to development for version 4. The previous `release/v2` branch remains supported during its grace period. - -## What belongs in major, minor, and patch releases - -Major releases are only time-based. They happen yearly and will include instructions for updating from previous long-term supported major versions. That means that minor updates can include all breaking changes, such as removal of support for PostgreSQL dependencies, - -## Upgrade path - -DocumentDB will support direct in-place upgrades between consecutive major versions. There is also a simple path from the current major release to the latest minor release of that same major. This will allow for a simple switch from long-term support to the latest builds. - -Release candidates are different. Upgrades from release candidate versions will not be supported. Release candidates use the same extension version as the first full release for that major, so there is no reliable extension upgrade path from an RC to the final release. diff --git a/blogs/_posts/2026-10-01-versioning.md b/blogs/_posts/2026-10-01-versioning.md new file mode 100644 index 0000000..9d7f342 --- /dev/null +++ b/blogs/_posts/2026-10-01-versioning.md @@ -0,0 +1,44 @@ +--- +title: "Long-term support or development? An explanation of DocumentDB's versioning" +description: A comparison DocumentDB's long-term support builds versus the latests development builds +date: 2026-10-01 +featured: true +author: DocumentDB team +category: documentdb-blog +tags: + - DocumentDB + - "1.0" + - Release + - Version +--- + +DocumentDB is releasing version 1.0 with long-term support, splitting from the main development branch that will continue with 1.1 and beyond. +This is to ensure there is a stable version of the platform for users who don't need the latest features. + +This post will also clarify what support really means, describe how we will handle future minor version updates (1.1, 1.2, etc.), and explain when updates to the different tracks will happen. + +## The long-term support track + +DocumentDB will publish one new major version each year. The major versions are on branches such as `release/v3`. +Security fixes will be backported to supported release branches, with new artifacts built until support ends. Other bug fixes will be backported case by case. +A major version will be supported in this way until three months after the next major version is released. + +Backports of security fixes will be added to the LTS version with a patch version bump. For example, a security fix could bump the long-term support branch to v3.0-1, but not v3.1-0. +The long-term support track will not get any minor updates, only patch updates. + +### Release candidates + +Release candidates use the `-RC` suffix. For example, a release candidate for version 3 could be tagged `v3.0-RC1`, followed by a final release tag such as `v3.0-0`. After the final release, `release/v3` becomes the supported branch for version 3, while `main` moves on to development for version 4. The previous `release/v2` branch remains supported during its grace period. + +## The main development track + +Major releases are time-based. Minor releases, however, will continue to be pushed out as they have been before, as development work completes. Instead of backporting, the artifacts on the main development track will be built only when the next minor version releases. In this way, all security and bug fixes will come as a user of the development track rolls forward with the latest minor updates. + +## Upgrade paths + +DocumentDB will support direct in-place upgrades between consecutive long-term support major versions. +For example, if you are using v1.0-2, and v2.0-0 is released as part of a new major, there will be instructions for how to update to that next version before v1.0 falls out of support. + +There is also a simple path from the current major release to the latest minor release of that same major. This will allow for a simple switch from long-term support to the latest builds. + +Release candidates are different. Upgrades from release candidate versions will not be supported. Release candidates use the same extension version as the first full release for that major, so there is no reliable extension upgrade path from an RC to the final release. From 314bfc914656abb1f0eac847f41b8655bf661451 Mon Sep 17 00:00:00 2001 From: Alexander Laye Date: Thu, 1 Oct 2026 16:22:13 -0400 Subject: [PATCH 3/4] Emphasize RC --- blogs/_posts/2026-10-01-versioning.md | 31 +++++++++++++++++++++------ 1 file changed, 24 insertions(+), 7 deletions(-) diff --git a/blogs/_posts/2026-10-01-versioning.md b/blogs/_posts/2026-10-01-versioning.md index 9d7f342..77b878b 100644 --- a/blogs/_posts/2026-10-01-versioning.md +++ b/blogs/_posts/2026-10-01-versioning.md @@ -1,6 +1,6 @@ --- title: "Long-term support or development? An explanation of DocumentDB's versioning" -description: A comparison DocumentDB's long-term support builds versus the latests development builds +description: A comparison DocumentDB's long-term support, development, and release-candidate builds date: 2026-10-01 featured: true author: DocumentDB team @@ -12,12 +12,33 @@ tags: - Version --- -DocumentDB is releasing version 1.0 with long-term support, splitting from the main development branch that will continue with 1.1 and beyond. +DocumentDB is releasing v1.0-RC1 for testing. This is a release candidate preceding the full 1.0 release. +Following the full release, DocumentDB will split the main development branch that will continue with 1.1 and beyond from the LTS branch that will stay at 1.0. This is to ensure there is a stable version of the platform for users who don't need the latest features. This post will also clarify what support really means, describe how we will handle future minor version updates (1.1, 1.2, etc.), and explain when updates to the different tracks will happen. -## The long-term support track +## Release candidates + +Release candidates use the `-RC` suffix. For example, a release candidate for version 3 could be tagged `v3.0-RC1`, followed by a final release tag such as `v3.0-0`. +After the final release, `release/v3` becomes the supported branch for version 3, while `main` moves on to development for version 4. The previous `release/v2` branch remains supported during its grace period. + +These experimental versions are not intended for long-term use, nor will they be supported past the full release. They are only for testing purposes, and if used should be used on a short-lived fresh instance. + +### Release candidate installation + +For installation instructions, see our [README.md](https://github.com/documentdb/documentdb/blob/main/packaging/README.md#clean-host-installer) +or use the command below. + +```bash +curl -fsSLo documentdb-install.sh \ + https://documentdb.io/install.sh && +sh documentdb-install.sh --version v1.0-RC1 +``` + +If you find any problems with the RC, please [create an issue on GitHub](https://github.com/documentdb/documentdb/issues). + +## Definition of support DocumentDB will publish one new major version each year. The major versions are on branches such as `release/v3`. Security fixes will be backported to supported release branches, with new artifacts built until support ends. Other bug fixes will be backported case by case. @@ -26,10 +47,6 @@ A major version will be supported in this way until three months after the next Backports of security fixes will be added to the LTS version with a patch version bump. For example, a security fix could bump the long-term support branch to v3.0-1, but not v3.1-0. The long-term support track will not get any minor updates, only patch updates. -### Release candidates - -Release candidates use the `-RC` suffix. For example, a release candidate for version 3 could be tagged `v3.0-RC1`, followed by a final release tag such as `v3.0-0`. After the final release, `release/v3` becomes the supported branch for version 3, while `main` moves on to development for version 4. The previous `release/v2` branch remains supported during its grace period. - ## The main development track Major releases are time-based. Minor releases, however, will continue to be pushed out as they have been before, as development work completes. Instead of backporting, the artifacts on the main development track will be built only when the next minor version releases. In this way, all security and bug fixes will come as a user of the development track rolls forward with the latest minor updates. From 4033f095b044231eb1341101a3bb73e933845d22 Mon Sep 17 00:00:00 2001 From: Alexander Laye Date: Fri, 2 Oct 2026 15:30:33 -0400 Subject: [PATCH 4/4] review comments --- blogs/_posts/2026-10-01-versioning.md | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/blogs/_posts/2026-10-01-versioning.md b/blogs/_posts/2026-10-01-versioning.md index 77b878b..65d6587 100644 --- a/blogs/_posts/2026-10-01-versioning.md +++ b/blogs/_posts/2026-10-01-versioning.md @@ -40,22 +40,24 @@ If you find any problems with the RC, please [create an issue on GitHub](https:/ ## Definition of support -DocumentDB will publish one new major version each year. The major versions are on branches such as `release/v3`. +DocumentDB aims to publish one new major version each year. The major versions are on branches such as `release/v3`. Security fixes will be backported to supported release branches, with new artifacts built until support ends. Other bug fixes will be backported case by case. -A major version will be supported in this way until three months after the next major version is released. +A major version will be supported until three months after the next major version is released. Backports of security fixes will be added to the LTS version with a patch version bump. For example, a security fix could bump the long-term support branch to v3.0-1, but not v3.1-0. The long-term support track will not get any minor updates, only patch updates. ## The main development track -Major releases are time-based. Minor releases, however, will continue to be pushed out as they have been before, as development work completes. Instead of backporting, the artifacts on the main development track will be built only when the next minor version releases. In this way, all security and bug fixes will come as a user of the development track rolls forward with the latest minor updates. +Major releases are time-based. Minor releases, however, will continue to be pushed out as development work completes. +The artifacts on the main development track will be built only on minor version releases. At that point the previous minor is deprecated and all development track users should update immediately. +In this way, all security and bug fixes will come as a user of the development track rolls forward with the latest minor updates. ## Upgrade paths DocumentDB will support direct in-place upgrades between consecutive long-term support major versions. For example, if you are using v1.0-2, and v2.0-0 is released as part of a new major, there will be instructions for how to update to that next version before v1.0 falls out of support. -There is also a simple path from the current major release to the latest minor release of that same major. This will allow for a simple switch from long-term support to the latest builds. +There is also a direct upgrade path from the current major release to the latest minor release of that same major. This will allow for a simple switch from long-term support to the latest builds. Release candidates are different. Upgrades from release candidate versions will not be supported. Release candidates use the same extension version as the first full release for that major, so there is no reliable extension upgrade path from an RC to the final release.