Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse files

Clarified policy for stable branches.

Thanks Ramiro Morales for the initial patch and
Preston Holmes for the review.
  • Loading branch information...
commit 01948e384f5508c126c7216e43db3654bf6330f0 1 parent 2699219
Tim Graham timgraham authored
Showing with 81 additions and 71 deletions.
  1. +45 −31 docs/internals/git.txt
  2. +36 −40 docs/internals/release-process.txt
76 docs/internals/git.txt
View
@@ -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
====
76 docs/internals/release-process.txt
View
@@ -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
Please sign in to comment.
Something went wrong with that request. Please try again.