226 lines
8.7 KiB
Plaintext
226 lines
8.7 KiB
Plaintext
========================
|
|
Django's release process
|
|
========================
|
|
|
|
.. _official-releases:
|
|
|
|
Official releases
|
|
=================
|
|
|
|
Since version 1.0, Django's release numbering works as follows:
|
|
|
|
* Versions are numbered in the form ``A.B`` or ``A.B.C``.
|
|
|
|
* ``A.B`` is the *major version* number. Each version will be mostly backwards
|
|
compatible with the previous release. Exceptions to this rule will be listed
|
|
in the release notes. When ``B == 9``, the next major release will be
|
|
``A+1.0``. For example, Django 2.0 will follow Django 1.9. There won't be
|
|
anything special about "dot zero" releases.
|
|
|
|
* ``C`` is the *minor version* number, which is incremented for bug and
|
|
security fixes. A new minor release will be 100% backwards-compatible with
|
|
the previous minor release. The only exception is when a security or data loss
|
|
issue can't be fixed without breaking backwards-compatibility. If this
|
|
happens, the release notes will provide detailed upgrade instructions.
|
|
|
|
* Before a new major release, we'll make alpha, beta, and release candidate
|
|
releases. These are of the form ``A.B alpha/beta/rc N``, which means the
|
|
``Nth`` alpha/beta/release candidate of version ``A.B``.
|
|
|
|
In git, each Django release will have a tag indicating its version number,
|
|
signed with the Django release key. 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 the Django project issues new releases for
|
|
security purposes, please see :doc:`our security policies <security>`.
|
|
|
|
.. glossary::
|
|
|
|
Major release
|
|
Major releases (A.B, A.B+1, etc.) will happen roughly every nine months --
|
|
see `release process`_, below for details. These releases will contain new
|
|
features, improvements to existing features, and such.
|
|
|
|
.. _internal-release-deprecation-policy:
|
|
|
|
A major release may deprecate certain features from previous releases. If a
|
|
feature is deprecated in version ``A.B``, it will continue to work in versions
|
|
``A.B`` and ``A.B+1`` but raise warnings. It will be removed in version
|
|
``A.B+2``.
|
|
|
|
So, for example, if we decided to start the deprecation of a function in
|
|
Django 1.7:
|
|
|
|
* Django 1.7 will contain a backwards-compatible replica of the function which
|
|
will raise a ``RemovedInDjango19Warning``. This warning is silent by
|
|
default; you can turn on display of these warnings with the ``-Wd`` option
|
|
of Python.
|
|
|
|
* Django 1.8 will still contain the backwards-compatible replica. This
|
|
warning becomes *loud* by default, and will likely be quite annoying.
|
|
|
|
* Django 1.9 will remove the feature outright.
|
|
|
|
Minor release
|
|
Minor releases (A.B.C, etc.) will be issued as needed, often to fix security
|
|
issues.
|
|
|
|
These releases will be 100% compatible with the associated major release,
|
|
unless this is impossible for security reasons or to prevent data loss.
|
|
So the answer to "should I upgrade to the latest minor release?" will always
|
|
be "yes."
|
|
|
|
.. _backwards-compatibility-policy:
|
|
|
|
Supported versions
|
|
==================
|
|
|
|
At any moment in time, Django's developer team will support a set of releases to
|
|
varying levels:
|
|
|
|
* The current development master will get new features and bug fixes
|
|
requiring major refactoring.
|
|
|
|
* Patches applied to the master branch must also be applied to the last major
|
|
release, to be released as the next minor release, when they fix critical
|
|
problems:
|
|
|
|
* Security issues.
|
|
|
|
* Data loss bugs.
|
|
|
|
* Crashing bugs.
|
|
|
|
* Major functionality bugs in newly-introduced features.
|
|
|
|
The rule of thumb is that fixes will be backported to the last major release
|
|
for bugs that would have prevented a release in the first place (release
|
|
blockers).
|
|
|
|
* Security fixes and data loss bugs will be applied to the current master, the
|
|
last two major releases, and the current :ref:`LTS release <lts-releases>`.
|
|
|
|
* Documentation fixes generally will be more freely backported to the last
|
|
release branch. That's because it's highly advantageous to have the docs for
|
|
the last release be up-to-date and correct, and the risk of introducing
|
|
regressions is much less of a concern.
|
|
|
|
As a concrete example, consider a moment in time halfway between the release of
|
|
Django 1.7 and 1.8. At this point in time:
|
|
|
|
* Features will be added to development master, to be released as Django 1.8.
|
|
|
|
* Critical bug fixes will be applied to the ``stable/1.7.x`` branch, and
|
|
released as 1.7.1, 1.7.2, etc.
|
|
|
|
* Security fixes and bug fixes for data loss issues will be applied to
|
|
``master`` and to the ``stable/1.7.x``, ``stable/1.6.x``, and
|
|
``stable/1.4.x`` (LTS) branches. They will trigger the release of ``1.7.1``,
|
|
``1.6.1``, ``1.4.1``, etc.
|
|
|
|
* Documentation fixes will be applied to master, and, if easily backported, to
|
|
the ``1.7.x`` and ``1.6.x`` branches.
|
|
|
|
.. _lts-releases:
|
|
|
|
Long-term support (LTS) releases
|
|
================================
|
|
|
|
Additionally, the Django team will occasionally designate certain releases
|
|
to be "Long-term support" (LTS) releases. LTS releases will get security and
|
|
data loss fixes applied for a guaranteed period of time, typically 3+ years,
|
|
regardless of the pace of releases afterwards.
|
|
|
|
The follow releases have been designated for long-term support:
|
|
|
|
* Django 1.8, supported for at least 3 years after its release (scheduled for
|
|
April 2015).
|
|
* Django 1.4, supported for 6 months after the release of Django 1.8. As
|
|
Django 1.8 is scheduled to be released around April 2015, support for 1.4
|
|
will end around October 2015.
|
|
|
|
.. _release-process:
|
|
|
|
Release process
|
|
===============
|
|
|
|
Django uses a time-based release schedule, with major (i.e. 1.8, 1.9, 2.0,
|
|
etc.) releases every nine months, or more, depending on features.
|
|
|
|
After each release, and after a suitable cooling-off period of a few weeks,
|
|
core developers will examine the landscape and announce a timeline for the
|
|
next release. Most releases will be scheduled in the 6-9 month range, but if
|
|
we have bigger features to develop we might schedule a longer period to
|
|
allow for more ambitious work.
|
|
|
|
Release cycle
|
|
-------------
|
|
|
|
Each release cycle will be split into three periods, each lasting roughly
|
|
one-third of the cycle:
|
|
|
|
Phase one: feature proposal
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
The first phase of the release process will be devoted to figuring out what
|
|
features to include in the next version. This should include a good deal of
|
|
preliminary work on those features -- working code trumps grand design.
|
|
|
|
At the end of part one, the core developers will propose a feature list for the
|
|
upcoming release. This will be broken into:
|
|
|
|
* "Must-have": critical features that will delay the release if not finished
|
|
* "Maybe" features: that will be pushed to the next release if not finished
|
|
* "Not going to happen": features explicitly deferred to a later release.
|
|
|
|
Anything that hasn't got at least some work done by the end of the first third
|
|
isn't eligible for the next release; a design alone isn't sufficient.
|
|
|
|
Phase two: development
|
|
~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
The second third of the release schedule is the "heads-down" working period.
|
|
Using the roadmap produced at the end of phase one, we'll all work very hard to
|
|
get everything on it done.
|
|
|
|
Longer release schedules will likely spend more than a third of the time in this
|
|
phase.
|
|
|
|
At the end of phase two, any unfinished "maybe" features will be postponed until
|
|
the next release. Though it shouldn't happen, any "must-have" features will
|
|
extend phase two, and thus postpone the final release.
|
|
|
|
Phase two will culminate with an alpha release. At this point, the
|
|
``stable/A.B.x`` branch will be forked from ``master``.
|
|
|
|
Phase three: bugfixes
|
|
~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
The last third of a release cycle is spent fixing bugs -- no new features will
|
|
be accepted during this time. We'll try to release a beta release after one
|
|
month and a release candidate after two months.
|
|
|
|
The release candidate marks the string freeze, and it happens at least two
|
|
weeks before the final release. After this point, new translatable strings
|
|
must not be added.
|
|
|
|
During this phase, committers will be more and more conservative with
|
|
backports, to avoid introducing regressions. After the release candidate, only
|
|
release blockers and documentation fixes should be backported.
|
|
|
|
In parallel to this phase, ``master`` can receive new features, to be released
|
|
in the ``A.B+1`` cycle.
|
|
|
|
Bug-fix releases
|
|
----------------
|
|
|
|
After a major release (e.g. A.B), the previous release will go into bugfix
|
|
mode.
|
|
|
|
The branch for the previous major release (e.g. ``stable/A.B-1.x``) will include
|
|
bugfixes. Critical bugs fixed on master 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 master will be responsible for
|
|
also applying the fix to the current bugfix branch.
|