252 lines
9.6 KiB
Plaintext
252 lines
9.6 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`` is the *major version* number, which is only incremented for major
|
|
changes to Django, and these changes are not necessarily
|
|
backwards-compatible. That is, code you wrote for Django 1.6 may break
|
|
when we release Django 2.0.
|
|
|
|
* ``B`` is the *minor version* number, which is incremented for large yet
|
|
backwards compatible changes. Code written for Django 1.6 will continue
|
|
to work under Django 1.7. Exceptions to this rule will be listed in the
|
|
release notes.
|
|
|
|
* ``C`` is the *micro version* number, which is incremented for bug and
|
|
security fixes. A new micro-release will be 100% backwards-compatible with
|
|
the previous micro-release. The only exception is when a security issue
|
|
can't be fixed without breaking backwards-compatibility. If this happens,
|
|
the release notes will provide detailed upgrade instructions.
|
|
|
|
* Before a new minor 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 (1.0, 2.0, etc.) will happen very infrequently (think "years",
|
|
not "months"), and may represent major, sweeping changes to Django.
|
|
|
|
Minor release
|
|
Minor release (1.5, 1.6, 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 minor 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.
|
|
|
|
Micro release
|
|
Micro releases (1.5.1, 1.6.2, 1.6.1, etc.) will be issued as needed, often to
|
|
fix security issues.
|
|
|
|
These releases will be 100% compatible with the associated minor release, unless
|
|
this is impossible for security reasons. So the answer to "should I upgrade to
|
|
the latest micro 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 minor
|
|
release, to be released as the next micro 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 minor release
|
|
for bugs that would have prevented a release in the first place (release
|
|
blockers).
|
|
|
|
* Security fixes will be applied to the current master and the previous two
|
|
minor releases.
|
|
|
|
* Committers may choose to backport bugfixes at their own discretion,
|
|
provided they do not introduce backwards incompatibilities.
|
|
|
|
* 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.6 and 1.7. At this point in time:
|
|
|
|
* Features will be added to development master, to be released as Django 1.7.
|
|
|
|
* Critical bug fixes will be applied to the ``stable/1.6.x`` branch, and
|
|
released as 1.6.1, 1.6.2, etc.
|
|
|
|
* Security fixes will be applied to ``master``, to the ``stable/1.6.x``
|
|
branch, and to the ``stable/1.5.x`` branch. They will trigger the release of
|
|
``1.6.1``, ``1.5.1``, etc.
|
|
|
|
* Documentation fixes will be applied to master, and, if easily backported, to
|
|
the ``1.6.x`` branch. Bugfixes may also be backported.
|
|
|
|
.. _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 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.4, supported until at least March 2015.
|
|
|
|
.. _release-process:
|
|
|
|
Release process
|
|
===============
|
|
|
|
Django uses a time-based release schedule, with minor (i.e. 1.6, 1.7, etc.)
|
|
releases every nine months, or more, depending on features.
|
|
|
|
After each release, and after a suitable cooling-off period of a few weeks, the
|
|
core development team 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 development 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 minor release (e.g. 1.6), the previous release will go into bugfix
|
|
mode.
|
|
|
|
A branch will be created of the form ``stable/1.5.x`` to track bugfixes to the
|
|
previous release. 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.
|
|
|
|
How this all fits together
|
|
--------------------------
|
|
|
|
Let's look at a hypothetical example for how this all first together. Imagine,
|
|
if you will, a point about halfway between 1.5 and 1.6. At this point,
|
|
development will be happening in a bunch of places:
|
|
|
|
* On master, development towards 1.6 proceeds with small additions, bugs
|
|
fixes, etc. being checked in daily.
|
|
|
|
* On the branch ``stable/1.5.x``, fixes for critical bugs found in
|
|
the 1.5 release are checked in as needed. At some point, this branch will
|
|
be released as "1.5.1", "1.5.2", etc.
|
|
|
|
* On the branch ``stable/1.4.x``, security fixes are made if
|
|
needed and released as "1.4.2", "1.4.3", etc.
|
|
|
|
* Development of major features is done in branches in forks of the main
|
|
repository. These branches will be merged into ``master`` before "1.6
|
|
alpha 1".
|