From 991d9bcab540126803454011d7c7efe2cba37bf3 Mon Sep 17 00:00:00 2001
From: Sage Abdullah <sage.abdullah@torchbox.com>
Date: Fri, 8 Nov 2024 20:08:42 +0000
Subject: [PATCH] Update release process documentation
---
docs/contributing/release_process.md | 137 +++++++++++++++++++--------
1 file changed, 95 insertions(+), 42 deletions(-)
diff --git a/docs/contributing/release_process.md b/docs/contributing/release_process.md
index 3c8ac0f278..a6cca7703d 100644
--- a/docs/contributing/release_process.md
+++ b/docs/contributing/release_process.md
@@ -7,8 +7,9 @@ Release numbering works as follows:
- Versions are numbered in the form `A.B` or `A.B.C`.
- `A.B` is the _feature release_ version number. Each version will be mostly
- backwards compatible with the previous release. Exceptions to this rule will
- be listed in the release notes.
+ backwards compatible with the previous release. Exceptions to this rule
+ will be listed in the release notes. When `B` is `0`, the release contains
+ backwards-incompatible changes.
- `C` is the _patch release_ version number, which is incremented for bugfix
and security releases. These releases will be 100% backwards-compatible with
@@ -25,6 +26,8 @@ Additionally, each release series has its
own branch, called `stable/A.B.x`, and bugfix/security releases will be
issued from those branches.
+For more information about how Wagtail issues new releases for security purposes, please see our [security policies](https://docs.wagtail.org/en/latest/contributing/security.html).
+
**Feature release**
Feature releases (A.B, A.B+1, etc.) happen every three months
@@ -41,13 +44,32 @@ unless this is impossible for security reasons or to prevent data loss.
So the answer to "should I upgrade to the latest patch release?" will always
be "yes."
+A feature release will usually stop receiving patch release updates when the next feature release comes out.
+
**Long-term support release**
Certain feature releases will be designated as long-term support (LTS)
releases. These releases will get security and data loss fixes applied for
-a guaranteed period of time, typically six months.
+a guaranteed period of time. Typically, a Long Term Support release will happen
+once every four feature releases and receive updates for five feature releases,
+giving a support period of fifteen months with a three month overlap.
-## Release cadence
+Also, Long Term Support releases will ensure compatibility with at least one [Django Long Term Support release](https://www.djangoproject.com/download/#supported-versions).
+
+**Major release**
+
+Certain feature releases (A.0, A+1.0, etc.) will be designated as major
+releases, marked by incrementing the first part of the version number. These
+releases will contain significant changes to the user interface or
+backwards-incompatible changes.
+
+Major releases do not happen on a regular schedule. Typically, they will happen
+when the previous feature releases have accumulated enough deprecated features
+that it's time to remove them.
+
+(deprecation_policy)=
+
+## Deprecation policy
Wagtail uses a loose form of [semantic versioning](https://semver.org/).
SemVer makes it easier to see at a glance how compatible releases are with each
@@ -56,23 +78,37 @@ It's not a pure form of SemVer as each feature release will continue to have a
few documented backwards incompatibilities where a deprecation path isn't
possible or not worth the cost.
-## Deprecation policy
+We try to strike the balance between:
+
+- keeping the API stable for most users,
+- documenting features for advanced developers and third-party package maintainers, and
+- allowing for continuous improvement of Wagtail's internals.
A feature release may deprecate certain features from previous releases. If a
-feature is deprecated in feature release A.B, it will continue to work in
-the following version but raise warnings. Features deprecated in release A.B
-will be removed in the A.B+2 release to ensure deprecations are done
-over at least 2 feature releases.
+feature is deprecated in feature release A.x, it will continue to work in all
+A.x versions (for all versions of x) but raise warnings. Deprecated features
+will be removed in the A+1.0 release, or A+2.0 for features deprecated in the
+last A.x feature release to ensure deprecations are done over at least 2
+feature releases.
-So, for example, if we decided to start the deprecation of a function in
-Wagtail 1.4:
+For example:
-- Wagtail 1.4 will contain a backwards-compatible replica of the function which
- will raise a `RemovedInWagtail16Warning`.
+- Wagtail 5.1 was released. Function `func_a()` that entered deprecation in
+ this version would have a backwards-compatible replica which would raise a
+ `RemovedInWagtail60Warning`.
-- Wagtail 1.5 will still contain the backwards-compatible replica.
+- Wagtail 5.2 was released. This version still contained the
+ backwards-compatible replica of `func_a()`. Future version numbers are
+ provisional, so the next version could either be 5.3 or 6.0. For function
+ `func_b()` that entered deprecation in version 5.2, it would tentatively
+ raise a `RemovedInWagtail60Warning`.
-- Wagtail 1.6 will remove the feature outright.
+- Wagtail 6.0 was decided to be the next version after Wagtail 5.2. In
+ this release, `func_a()` was outright removed, and `func_b()` would raise a
+ `RemovedInWagtail70Warning` instead.
+
+- When Wagtail 7.0 is released (after all 6.x versions), `func_b()` will be
+ removed.
The warnings are silent by default. You can turn on display of these warnings
with the `python -Wd` option.
@@ -113,19 +149,19 @@ varying levels.
regressions is much less of a concern.
As a concrete example, consider a moment in time halfway between the release of
-Wagtail 1.6 and 1.7. At this point in time:
+Wagtail 6.1 and 6.2. At this point in time:
-- Features will be added to `main`, to be released as Wagtail 1.7.
+- Features will be added to `main`, to be released as Wagtail 6.2.
-- Critical bug fixes will be applied to the `stable/1.6.x` branch, and
- released as 1.6.1, 1.6.2, etc.
+- Critical bug fixes will be applied to the `stable/6.1.x` branch, and
+ released as 6.1.1, 6.1.3, etc.
- Security fixes and bug fixes for data loss issues will be applied to
- `main` and to the `stable/1.6.x` and `stable/1.4.x` (LTS) branches.
- They will trigger the release of `1.6.1`, `1.4.8`, etc.
+ `main` and to the `stable/6.1.x` and `stable/5.2.x` (LTS) branches.
+ They will trigger the release of `6.1.3`, `5.2.6`, etc.
- Documentation fixes will be applied to `main`, and, if easily backported, to
- the latest stable branch, `1.6.x`.
+ the latest stable branch, `stable/6.1.x`.
## Supported versions of Django
@@ -134,16 +170,23 @@ Each release of Wagtail declares which versions of Django it supports.
Typically, a new Wagtail feature release supports the last long-term support version and
all following versions of Django.
-For example, consider a moment in time before release of Wagtail 1.5
-and after the following releases:
+For example, consider a moment in time before the release of Wagtail 6.3 and
+after the following releases:
-- Django 1.8 (LTS)
-- Django 1.9
-- Wagtail 1.4 (LTS) - Released before Django 1.10 and supports Django 1.8 and 1.9
-- Django 1.10
+- Django 4.2 (LTS)
+- Django 5.0
+- Wagtail 6.2 - Released before Django 5.1 and supports Django 4.2 and 5.0
+- Django 5.1
-Wagtail 1.5 will support Django 1.8 (LTS), 1.9, 1.10.
-Wagtail 1.4 will still support only Django 1.8 (LTS) and 1.9.
+Wagtail 6.3 will support Django 4.2 (LTS), 5.0, 5.1.
+Wagtail 6.2 will still support only Django 4.2 (LTS) and 5.0.
+
+In some cases, the latest Wagtail feature release falls in between the beta and
+final release of a new Django version. In such cases, the Wagtail release may
+add official support for the new Django version in a patch release. An example
+of this was Wagtail 5.2, which added support for Django 5.0 in Wagtail 5.2.2.
+
+For a list of supported Django and Python versions for each Wagtail release, see the [](compatible_django_python_versions) table.
(release_schedule)=
@@ -152,19 +195,22 @@ Wagtail 1.4 will still support only Django 1.8 (LTS) and 1.9.
Wagtail uses a [time-based release schedule](https://github.com/wagtail/wagtail/wiki/Release-schedule),
with feature releases every three months.
-After each feature release, the release manager will announce a timeline for
-the next feature release.
-
### Release cycle
Each release cycle consists of three parts:
-#### Phase one: feature proposal
+#### Phase one: roadmap update
The first phase of the release process will include figuring out what major
features to include in the next version. This should include a good deal of
preliminary work on those features -- working code trumps grand design.
+The development team will announce a roadmap update for the next feature
+release in the form of an RFC to
+[Wagtail's RFCs repository](https://github.com/wagtail/rfcs). After the RFC is
+approved, the roadmap update will be available on
+[wagtail.org/roadmap](https://wagtail.org/roadmap).
+
#### Phase two: development
The second part of the release schedule is the "heads-down" working period.
@@ -197,13 +243,20 @@ will be re-imported immediately before the final release.
In parallel to this phase, `main` can receive new features, to be released
in the `A.B+1` cycle.
-### Bug-fix releases
+### Patch releases
-After a feature release `A.B`, the previous release will go into bugfix
-mode.
+After a feature release `A.B`, the previous release will go into security
+support mode.
-The branch for the previous feature release `stable/A.B-1.x` will
-include bugfixes. Critical bugs fixed on `main` must _also_ be fixed on the
-bugfix branch; this means that commits need to cleanly separate bug fixes from
-feature additions. The developer who commits a fix to `main` will be
-responsible for also applying the fix to the current bugfix branch.
+The branches for the current feature release `stable/A.B.x` and the last LTS release will receive critical bug, security, and data loss fixes.
+
+The branch for the previous feature release `stable/A.B-1.x` will only include security and data loss fixes.
+
+Bugs fixed on `main` must _also_ be fixed on other applicable branches; this
+means that commits need to cleanly separate bug fixes from feature additions.
+The developer who commits a fix to `main` will be responsible for also applying
+the fix to the respective branches.
+
+## Acknowledgement
+
+This release process is based on [](inv:django#internals/release-process).