Updated release process for new release schedule.

This commit is contained in:
Tim Graham 2015-06-20 08:58:10 -04:00
parent bdb382b2a4
commit aed437d567
12 changed files with 155 additions and 143 deletions

View File

@ -46,11 +46,11 @@ translating or add a language that isn't yet translated, here's what to do:
`Transifex User Guide`_.
Translations from Transifex are only integrated into the Django repository at
the time of a new major release. We try to update them a second time during one
of the following minor releases, but that depends on the translation manager's
availability. So don't miss the string freeze period (between the release
candidate and the major release) to take the opportunity to complete and fix
the translations for your language!
the time of a new :term:`feature release`. We try to update them a second time
during one of the following :term:`patch release`\s, but that depends on the
translation manager's availability. So don't miss the string freeze period
(between the release candidate and the feature release) to take the opportunity
to complete and fix the translations for your language!
Formats
-------

View File

@ -236,11 +236,11 @@ Finally, there are a couple of updates to Django's documentation to make:
the "Features deprecated in A.B" heading.
#) Add an entry in the deprecation timeline (``docs/internals/deprecation.txt``)
under the ``A.B+2`` version describing what code will be removed.
under the appropriate version describing what code will be removed.
Once you have completed these steps, you are finished with the deprecation.
In each major release, all ``RemovedInDjangoXXWarning``\s matching the new
version are removed.
In each :term:`feature release`, all ``RemovedInDjangoXXWarning``\s matching
the new version are removed.
JavaScript patches
------------------

View File

@ -192,7 +192,7 @@ __ http://sphinx-doc.org/markup/
To link, use ``:djadminopt:`--traceback```.
* Links to Trac tickets (typically reserved for minor release notes)::
* Links to Trac tickets (typically reserved for patch release notes)::
:ticket:`12345`

View File

@ -36,8 +36,8 @@ The Git repository includes several `branches`_:
activity is focused.
* ``stable/A.B.x`` are the branches where release preparation work happens.
They are also used for support and bugfix releases which occur as necessary
after the initial release of a major or minor version.
They are also used for bugfix and security releases which occur as necessary
after the initial release of a feature version.
* ``soc20XX/<project>`` branches were used by students who worked on Django
during the 2009 and 2010 Google Summer of Code programs.
@ -84,8 +84,7 @@ coding style and how to generate and submit a patch.
Other branches
==============
Django uses branches to prepare for releases of Django (whether they be
:term:`major <Major release>` or :term:`minor <Minor release>`).
Django uses branches to prepare for releases of Django.
In the past when Django was hosted on Subversion, branches were also used for
feature development. Now Django is hosted on Git and feature development is

View File

@ -112,7 +112,7 @@ any time leading up to the actual release:
#. Double-check that the release notes index has a link to the notes
for the new release; this will be in ``docs/releases/index.txt``.
#. If this is a major release, ensure translations from Transifex have been
#. If this is a feature release, ensure translations from Transifex have been
integrated. This is typically done by a separate translation's manager
rather than the releaser, but here are the steps. Provided you have an
account on Transifex::
@ -181,9 +181,9 @@ OK, this is the fun part, where we actually push out a release!
__ https://github.com/django/django/commit/3ef4bbf495cc6c061789132e3d50a8231a89406b
#. For a major version release, remove the ``UNDER DEVELOPMENT`` header at the
#. For a feature release, remove the ``UNDER DEVELOPMENT`` header at the
top of the release notes and add the release date on the next line. For a
minor release, replace ``*Under Development*`` with the release date. Make
patch release, replace ``*Under Development*`` with the release date. Make
this change on all branches where the release notes for a particular version
are located.
@ -377,9 +377,9 @@ need to be done by the releaser.
``docs/fixtures/doc_releases.json`` JSON fixture, so people without access
to the production DB can still run an up-to-date copy of the docs site.
#. Create a stub release note for the new major version. Use the stub from the
previous major version or use the previous major version and delete most of
the contents leaving only section headings.
#. Create a stub release note for the new feature version. Use the stub from
the previous feature release version or copy the contents from the previous
feature version and delete most of the contents leaving only the headings.
#. Increase the default PBKDF2 iterations in
``django.contrib.auth.hashers.PBKDF2PasswordHasher`` by about 20%

View File

@ -166,7 +166,7 @@ The technical board is an elected group of five committers. They're expected
to be experienced but there's no formal seniority requirement. Its current
composition is published :ref:`here <technical-board-list>`.
A new board is elected after each major release of Django. The election
A new board is elected after each feature release of Django. The election
process is managed by a returns officer nominated by the outgoing technical
board. The election process works as follows:

View File

@ -11,19 +11,17 @@ 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.
* ``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.
* ``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
* ``C`` is the *patch release* version number, which is incremented for bugfix
and security releases. These releases will be 100% backwards-compatible with
the previous patch 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
* Before a new feature 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``.
@ -37,39 +35,84 @@ 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
Feature release
Feature releases (A.B, A.B+1, etc.) will happen roughly every eight months
-- see `release process`_ for details. These releases will contain new
features, improvements to existing features, and such.
Patch release
Patch releases (A.B.C, A.B.C+1, etc.) will be issued as needed, to fix
bugs and/or security issues.
These releases will be 100% compatible with the associated feature release,
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."
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 three years.
See `the download page`_ for the releases that have been designated for
long-term support.
.. _the download page: https://www.djangoproject.com/download/
Release cadence
===============
Starting with Django 2.0, version numbers will use a loose form of `semantic
versioning <http://semver.org/>`_ such that each version following an LTS will
bump to the next "dot zero" version. For example: 2.0, 2.1, 2.2 (LTS), 3.0,
3.1, 3.2 (LTS), etc.
SemVer makes it easier to see at a glance how compatible releases are with each
other. It also helps to anticipate when compatibility shims will be removed.
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. Also, deprecations started in an LTS release
(X.2) will be dropped in a non-dot-zero release (Y.1) to accommodate our policy
of keeping deprecation shims for at least two feature releases. Read on to the
next section for an example.
.. _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``.
Deprecation policy
==================
A feature release may deprecate certain features from previous releases. If a
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 B.0 release, or B.1 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
Django 1.7:
Django 4.2:
* Django 1.7 will contain a backwards-compatible replica of the function which
will raise a ``RemovedInDjango19Warning``. This warning is silent by
* Django 4.2 will contain a backwards-compatible replica of the function which
will raise a ``RemovedInDjango51Warning``. 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 5.0 (the version that follows 4.2) 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.
* Django 5.1 will remove the feature outright.
Minor release
Minor releases (A.B.C, etc.) will be issued as needed, often to fix security
issues.
A more generic example:
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."
* X.0
* X.1
* X.2 LTS
* Y.0: Drop deprecation shims added in X.0 and X.1.
* Y.1: Drop deprecation shims added in X.2.
* Y.2 LTS: No deprecation shims dropped (while Y.0 is no longer supported,
third-party apps need to maintain compatibility back to X.2 LTS to ease
LTS to LTS upgrades).
* Z.0: Drop deprecation shims added in Y.0 and Y.1.
.. _backwards-compatibility-policy:
@ -81,11 +124,11 @@ varying levels. See `the download page`_ for the current state of support for
each version.
* The current development master will get new features and bug fixes
requiring major refactoring.
requiring non-trivial 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:
* Patches applied to the master branch must also be applied to the last feature
release branch, to be released in the next patch release of that feature
series, when they fix critical problems:
* Security issues.
@ -95,12 +138,13 @@ each version.
* 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).
The rule of thumb is that fixes will be backported to the last feature
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>`.
last two feature release branches, and any other supported long-term
support release branches.
* 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
@ -108,86 +152,55 @@ each version.
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:
Django 5.1 and 5.2. At this point in time:
* Features will be added to development master, to be released as Django 1.8.
* Features will be added to development master, to be released as Django 5.2.
* Critical bug fixes will be applied to the ``stable/1.7.x`` branch, and
released as 1.7.1, 1.7.2, etc.
* Critical bug fixes will be applied to the ``stable/5.1.x`` branch, and
released as 5.1.1, 5.1.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.
``master`` and to the ``stable/5.1.x``, and ``stable/4.2.x`` (LTS) branches.
They will trigger the release of ``5.1.1``, ``4.2.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.
See `the download page`_ for the releases that have been designated for
long-term support.
.. _the download page: https://www.djangoproject.com/download/
the latest stable branch, ``5.1.x``.
.. _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.
Django uses a time-based release schedule, with feature releases every eight
months or so.
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.
After each feature release, the release manager will announce a timeline for
the next feature release.
Release cycle
-------------
Each release cycle will be split into three periods, each lasting roughly
one-third of the cycle:
Each release cycle consists of three parts:
Phase one: feature proposal
~~~~~~~~~~~~~~~~~~~~~~~~~~~
The first phase of the release process will be devoted to figuring out what
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.
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.
Major features for an upcoming release will be added to the wiki roadmap page,
e.g. https://code.djangoproject.com/wiki/Version1.9Roadmap.
Phase two: development
~~~~~~~~~~~~~~~~~~~~~~
The second third of the release schedule is the "heads-down" working period.
The second part 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.
At the end of phase two, any unfinished features will be postponed until the
next release.
Phase two will culminate with an alpha release. At this point, the
``stable/A.B.x`` branch will be forked from ``master``.
@ -195,9 +208,9 @@ Phase two will culminate with an alpha release. At this point, the
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 last part 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 one month
after the alpha and a release candidate one month after the beta.
The release candidate marks the string freeze, and it happens at least two
weeks before the final release. After this point, new translatable strings
@ -213,11 +226,11 @@ in the ``A.B+1`` cycle.
Bug-fix releases
----------------
After a major release (e.g. A.B), the previous release will go into bugfix
After a feature 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.
The branch for the previous feature 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.

View File

@ -59,8 +59,8 @@ for several versions of Django:
Django 1.3. Upon the release of Django 1.5, Django 1.3's security
support will end.
* :ref:`Long-term support (LTS) releases <lts-releases>` will receive
security updates for a specified period.
* :term:`Long-term support release`\s will receive security updates for a
specified period.
When new releases are issued for security reasons, the accompanying
notice will include a list of affected versions. This list is

View File

@ -2,13 +2,12 @@
API stability
=============
:doc:`The release of Django 1.0 </releases/1.0>` comes with a promise of API
stability and forwards-compatibility. In a nutshell, this means that code you
develop against a 1.X version of Django will continue to work with future
1.X releases. You may need to make minor changes when upgrading the version of
Django your project uses: see the "Backwards incompatible changes" section of
the :doc:`release note </releases/index>` for the version or versions to which
you are upgrading.
Django promises API stability and forwards-compatibility since version 1.0. In
a nutshell, this means that code you develop against a version of Django will
continue to work with future releases. You may need to make minor changes when
upgrading the version of Django your project uses: see the "Backwards
incompatible changes" section of the :doc:`release note </releases/index>` for
the version or versions to which you are upgrading.
What "stable" means
===================
@ -24,8 +23,8 @@ In this context, stable means:
- If, for some reason, an API declared stable must be removed or replaced, it
will be declared deprecated but will remain in the API for at least two
minor version releases. Warnings will be issued when the deprecated method
is called.
feature releases. Warnings will be issued when the deprecated method is
called.
See :ref:`official-releases` for more details on how Django's version
numbering scheme works, and how features will be deprecated.

View File

@ -12,10 +12,10 @@ incompatible changes`_ you'll want to be aware of when upgrading from Django
features`_, and some features have reached the end of their deprecation process
and `have been removed`_.
Django 1.8 has been designated as Django's second :ref:`"Long-Term Support"
(LTS) <lts-releases>` release. It will receive security updates for at least
three years after its release. Support for the previous LTS, Django 1.4, will
end 6 months from the release date of Django 1.8.
Django 1.8 has been designated as Django's second :term:`long-term support
release`. It will receive security updates for at least three years after its
release. Support for the previous LTS, Django 1.4, will end 6 months from the
release date of Django 1.8.
.. _`new features`: `What's new in Django 1.8`_
.. _`backwards incompatible changes`: `Backwards incompatible changes in 1.8`_

View File

@ -15,7 +15,7 @@ version.
Final releases
==============
Below are release notes through Django |version| and its minor releases. Newer
Below are release notes through Django |version| and its patch releases. Newer
versions of the documentation contain the release notes for any later releases.
.. _development_release_notes:

View File

@ -376,9 +376,10 @@ similar to the following::
'id': 'fields.W900', # pick a unique ID for your field.
}
After a deprecation period of your choosing (two major releases for fields in
Django itself), change the ``system_check_deprecated_details`` attribute to
``system_check_removed_details`` and update the dictionary similar to::
After a deprecation period of your choosing (two or three feature releases for
fields in Django itself), change the ``system_check_deprecated_details``
attribute to ``system_check_removed_details`` and update the dictionary similar
to::
class IPAddressField(Field):
system_check_removed_details = {