Skip to content
Browse files

Clarified policy for stable branches.

Thanks Ramiro Morales for the initial patch and
Preston Holmes for the review.
  • Loading branch information...
1 parent 2699219 commit 01948e384f5508c126c7216e43db3654bf6330f0 @timgraham timgraham committed
Showing with 81 additions and 71 deletions.
  1. +45 −31 docs/internals/git.txt
  2. +36 −40 docs/internals/release-process.txt
View
76 docs/internals/git.txt
@@ -35,8 +35,9 @@ The Git repository includes several `branches`_:
the next packaged release of Django. This is where most development
activity is focused.
-* ``stable/A.B.x`` are the maintenance branches. They are used to support
- older versions of Django.
+* ``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.
* ``soc20XX/<project>`` branches were used by students who worked on Django
during the 2009 and 2010 Google Summer of Code programs.
@@ -83,13 +84,50 @@ coding style and how to generate and submit a patch.
Other branches
==============
-Django uses branches for two main purposes:
+Django uses branches to prepare for releases of Django (whether they be
+:term:`major <Major release>`, :term:`minor <Minor release>`, or
+:term:`micro <Micro release>`).
-1. Development of major or experimental features, to keep them from
- affecting progress on other work in master.
+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
+done on contributor's forks, but the Subversion feature branches remain in Git
+for historical reference.
-2. Security and bugfix support for older releases of Django, during
- their support lifetimes.
+Stable branches
+---------------
+
+These branches can be found in the repository as ``stable/A.B.x``
+branches and will be created right after the first alpha is tagged.
+
+For example, immediately after *Django 1.5 alpha 1* was tagged, the branch
+``stable/1.5.x`` was created and all further work on preparing the code for the
+final 1.5 release was done there.
+
+These branches also provide limited bugfix support for the most recent released
+version of Django and security support for the two most recently-released
+versions of Django.
+
+For example, after the release of Django 1.5, the branch ``stable/1.5.x``
+receives only fixes for security and critical stability bugs, which are
+eventually released as Django 1.5.1 and so on, ``stable/1.4.x`` receives only
+security fixes, and ``stable/1.3.x`` no longer receives any updates.
+
+.. admonition:: Historical information
+
+ This policy for handling ``stable/A.B.x`` branches was adopted starting
+ with the Django 1.5 release cycle.
+
+ Previously, these branches weren't created until right after the releases
+ and the stabilization work occurred on the main repository branch. Thus,
+ no new features development work for the next release of Django could be
+ committed until the final release happened.
+
+ For example, shortly after the release of Django 1.3 the branch
+ ``stable/1.3.x`` was created. Official support for that release has expired,
+ and so it no longer receives direct maintenance from the Django project.
+ However, that and all other similarly named branches continue to exist and
+ interested community members have occasionally used them to provide
+ unofficial support for old Django releases.
Feature-development branches
----------------------------
@@ -203,30 +241,6 @@ All of the above-mentioned branches now reside in ``attic``.
Finally, the repository contains ``soc2009/xxx`` and ``soc2010/xxx`` feature
branches, used for Google Summer of Code projects.
-Support and bugfix branches
----------------------------
-
-In addition to fixing bugs in current master, the Django project provides
-official bugfix support for the most recent released version of Django, and
-security support for the two most recently-released versions of Django.
-
-This support is provided via branches in which the necessary bug or security
-fixes are applied; the branches are then used as the basis for issuing bugfix
-or security releases.
-
-These branches can be found in the repository as ``stable/A.B.x``
-branches, and new branches will be created there after each new Django
-release.
-
-For example, shortly after the release of Django 1.0, the branch
-``stable/1.0.x`` was created to receive bug fixes, and shortly after the
-release of Django 1.1 the branch ``stable/1.1.x`` was created.
-
-Official support for the above mentioned releases has expired, and so they no
-longer receive direct maintenance from the Django project. However, the
-branches continue to exist and interested community members have occasionally
-used them to provide unofficial support for old Django releases.
-
Tags
====
View
76 docs/internals/release-process.txt
@@ -39,49 +39,45 @@ 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>`.
-Major releases
---------------
+.. glossary::
-Major releases (1.0, 2.0, etc.) will happen very infrequently (think "years",
-not "months"), and may represent major, sweeping changes to Django.
+ 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 releases
---------------
+ 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.
-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:
-.. _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``.
-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.5:
-So, for example, if we decided to start the deprecation of a function in
-Django 1.5:
+ * Django 1.5 will contain a backwards-compatible replica of the function which
+ will raise a ``PendingDeprecationWarning``. This warning is silent by
+ default; you can turn on display of these warnings with the ``-Wd`` option
+ of Python.
-* Django 1.5 will contain a backwards-compatible replica of the function which
- will raise a ``PendingDeprecationWarning``. This warning is silent by
- default; you can turn on display of these warnings with the ``-Wd`` option
- of Python.
+ * Django 1.6 will contain the backwards-compatible replica, but the warning
+ will be promoted to a full-fledged ``DeprecationWarning``. This warning is
+ *loud* by default, and will likely be quite annoying.
-* Django 1.6 will contain the backwards-compatible replica, but the warning
- will be promoted to a full-fledged ``DeprecationWarning``. This warning is
- *loud* by default, and will likely be quite annoying.
+ * Django 1.7 will remove the feature outright.
-* Django 1.7 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.
-Micro releases
---------------
-
-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."
+ 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:
@@ -126,15 +122,15 @@ 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
+* 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
+* 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.
+ the ``1.6.x`` branch. Bugfixes may also be backported.
.. _release-process:
@@ -193,9 +189,9 @@ Phase two will culminate with an alpha release. At this point, the
Phase three: bugfixes
~~~~~~~~~~~~~~~~~~~~~
-The last third of a release 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 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

0 comments on commit 01948e3

Please sign in to comment.
Something went wrong with that request. Please try again.