From 991d9bcab540126803454011d7c7efe2cba37bf3 Mon Sep 17 00:00:00 2001 From: Sage Abdullah 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).