mirror of
https://github.com/wagtail/wagtail.git
synced 2024-11-21 18:09:02 +01:00
Update release process documentation
This commit is contained in:
Sage Abdullah
parent
f43cf941d5
commit
991d9bcab5
@ -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).
|
||||
|
||||
Loading…
Reference in New Issue
Block a user