Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse code

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 authored
76  docs/internals/git.txt
@@ -35,8 +35,9 @@ The Git repository includes several `branches`_:
35 35
   the next packaged release of Django. This is where most development
36 36
   activity is focused.
37 37
 
38  
-* ``stable/A.B.x`` are the maintenance branches. They are used to support
39  
-  older versions of Django.
  38
+* ``stable/A.B.x`` are the branches where release preparation work happens.
  39
+  They are also used for support and bugfix releases which occur as necessary
  40
+  after the initial release of a major or minor version.
40 41
 
41 42
 * ``soc20XX/<project>`` branches were used by students who worked on Django
42 43
   during the 2009 and 2010 Google Summer of Code programs.
@@ -83,13 +84,50 @@ coding style and how to generate and submit a patch.
83 84
 Other branches
84 85
 ==============
85 86
 
86  
-Django uses branches for two main purposes:
  87
+Django uses branches to prepare for releases of Django (whether they be
  88
+:term:`major <Major release>`, :term:`minor <Minor release>`, or
  89
+:term:`micro <Micro release>`).
87 90
 
88  
-1. Development of major or experimental features, to keep them from
89  
-   affecting progress on other work in master.
  91
+In the past when Django was hosted on Subversion, branches were also used for
  92
+feature development. Now Django is hosted on Git and feature development is
  93
+done on contributor's forks, but the Subversion feature branches remain in Git
  94
+for historical reference.
90 95
 
91  
-2. Security and bugfix support for older releases of Django, during
92  
-   their support lifetimes.
  96
+Stable branches
  97
+---------------
  98
+
  99
+These branches can be found in the repository as ``stable/A.B.x``
  100
+branches and will be created right after the first alpha is tagged.
  101
+
  102
+For example, immediately after *Django 1.5 alpha 1* was tagged, the branch
  103
+``stable/1.5.x`` was created and all further work on preparing the code for the
  104
+final 1.5 release was done there.
  105
+
  106
+These branches also provide limited bugfix support for the most recent released
  107
+version of Django and security support for the two most recently-released
  108
+versions of Django.
  109
+
  110
+For example, after the release of Django 1.5, the branch ``stable/1.5.x``
  111
+receives only fixes for security and critical stability bugs, which are
  112
+eventually released as Django 1.5.1 and so on, ``stable/1.4.x`` receives only
  113
+security fixes, and ``stable/1.3.x`` no longer receives any updates.
  114
+
  115
+.. admonition:: Historical information
  116
+
  117
+    This policy for handling ``stable/A.B.x`` branches was adopted starting
  118
+    with the Django 1.5 release cycle.
  119
+
  120
+    Previously, these branches weren't created until right after the releases
  121
+    and the stabilization work occurred on the main repository branch. Thus,
  122
+    no new features development work for the next release of Django could be
  123
+    committed until the final release happened.
  124
+
  125
+    For example, shortly after the release of Django 1.3 the branch
  126
+    ``stable/1.3.x`` was created. Official support for that release has expired,
  127
+    and so it no longer receives direct maintenance from the Django project.
  128
+    However, that and all other similarly named branches continue to exist and
  129
+    interested community members have occasionally used them to provide
  130
+    unofficial support for old Django releases.
93 131
 
94 132
 Feature-development branches
95 133
 ----------------------------
@@ -203,30 +241,6 @@ All of the above-mentioned branches now reside in ``attic``.
203 241
 Finally, the repository contains ``soc2009/xxx`` and ``soc2010/xxx`` feature
204 242
 branches, used for Google Summer of Code projects.
205 243
 
206  
-Support and bugfix branches
207  
----------------------------
208  
-
209  
-In addition to fixing bugs in current master, the Django project provides
210  
-official bugfix support for the most recent released version of Django, and
211  
-security support for the two most recently-released versions of Django.
212  
-
213  
-This support is provided via branches in which the necessary bug or security
214  
-fixes are applied; the branches are then used as the basis for issuing bugfix
215  
-or security releases.
216  
-
217  
-These branches can be found in the repository as ``stable/A.B.x``
218  
-branches, and new branches will be created there after each new Django
219  
-release.
220  
-
221  
-For example, shortly after the release of Django 1.0, the branch
222  
-``stable/1.0.x`` was created to receive bug fixes, and shortly after the
223  
-release of Django 1.1 the branch ``stable/1.1.x`` was created.
224  
-
225  
-Official support for the above mentioned releases has expired, and so they no
226  
-longer receive direct maintenance from the Django project. However, the
227  
-branches continue to exist and interested community members have occasionally
228  
-used them to provide unofficial support for old Django releases.
229  
-
230 244
 Tags
231 245
 ====
232 246
 
76  docs/internals/release-process.txt
@@ -39,49 +39,45 @@ issued from those branches.
39 39
 For more information about how the Django project issues new releases for
40 40
 security purposes, please see :doc:`our security policies <security>`.
41 41
 
42  
-Major releases
43  
---------------
  42
+.. glossary::
44 43
 
45  
-Major releases (1.0, 2.0, etc.) will happen very infrequently (think "years",
46  
-not "months"), and may represent major, sweeping changes to Django.
  44
+  Major release
  45
+    Major releases (1.0, 2.0, etc.) will happen very infrequently (think "years",
  46
+    not "months"), and may represent major, sweeping changes to Django.
47 47
 
48  
-Minor releases
49  
---------------
  48
+  Minor release
  49
+    Minor release (1.5, 1.6, etc.) will happen roughly every nine months -- see
  50
+    `release process`_, below for details. These releases will contain new
  51
+    features, improvements to existing features, and such.
50 52
 
51  
-Minor release (1.5, 1.6, etc.) will happen roughly every nine months -- see
52  
-`release process`_, below for details. These releases will contain new
53  
-features, improvements to existing features, and such.
  53
+    .. _internal-release-deprecation-policy:
54 54
 
55  
-.. _internal-release-deprecation-policy:
  55
+    A minor release may deprecate certain features from previous releases. If a
  56
+    feature is deprecated in version ``A.B``, it will continue to work in versions
  57
+    ``A.B`` and  ``A.B+1`` but raise warnings. It will be removed in version
  58
+    ``A.B+2``.
56 59
 
57  
-A minor release may deprecate certain features from previous releases. If a
58  
-feature is deprecated in version ``A.B``, it will continue to work in versions
59  
-``A.B`` and  ``A.B+1`` but raise warnings. It will be removed in version
60  
-``A.B+2``.
  60
+    So, for example, if we decided to start the deprecation of a function in
  61
+    Django 1.5:
61 62
 
62  
-So, for example, if we decided to start the deprecation of a function in
63  
-Django 1.5:
  63
+    * Django 1.5 will contain a backwards-compatible replica of the function which
  64
+      will raise a ``PendingDeprecationWarning``. This warning is silent by
  65
+      default; you can turn on display of these warnings with the ``-Wd`` option
  66
+      of Python.
64 67
 
65  
-* Django 1.5 will contain a backwards-compatible replica of the function which
66  
-  will raise a ``PendingDeprecationWarning``. This warning is silent by
67  
-  default; you can turn on display of these warnings with the ``-Wd`` option
68  
-  of Python.
  68
+    * Django 1.6 will contain the backwards-compatible replica, but the warning
  69
+      will be promoted to a full-fledged ``DeprecationWarning``. This warning is
  70
+      *loud* by default, and will likely be quite annoying.
69 71
 
70  
-* Django 1.6 will contain the backwards-compatible replica, but the warning
71  
-  will be promoted to a full-fledged ``DeprecationWarning``. This warning is
72  
-  *loud* by default, and will likely be quite annoying.
  72
+    * Django 1.7 will remove the feature outright.
73 73
 
74  
-* Django 1.7 will remove the feature outright.
  74
+  Micro release
  75
+    Micro releases (1.5.1, 1.6.2, 1.6.1, etc.) will be issued as needed, often to
  76
+    fix security issues.
75 77
 
76  
-Micro releases
77  
---------------
78  
-
79  
-Micro releases (1.5.1, 1.6.2, 1.6.1, etc.) will be issued as needed, often to
80  
-fix security issues.
81  
-
82  
-These releases will be 100% compatible with the associated minor release, unless
83  
-this is impossible for security reasons. So the answer to "should I upgrade to
84  
-the latest micro release?" will always be "yes."
  78
+    These releases will be 100% compatible with the associated minor release, unless
  79
+    this is impossible for security reasons. So the answer to "should I upgrade to
  80
+    the latest micro release?" will always be "yes."
85 81
 
86 82
 .. _backwards-compatibility-policy:
87 83
 
@@ -126,15 +122,15 @@ Django 1.6 and 1.7. At this point in time:
126 122
 
127 123
 * Features will be added to development master, to be released as Django 1.7.
128 124
 
129  
-* Critical bug fixes will be applied to the ``stable/1.6.X`` branch, and
  125
+* Critical bug fixes will be applied to the ``stable/1.6.x`` branch, and
130 126
   released as 1.6.1, 1.6.2, etc.
131 127
 
132  
-* Security fixes will be applied to ``master``, to the ``stable/1.6.X``
133  
-  branch, and to the ``stable/1.5.X`` branch. They will trigger the release of
  128
+* Security fixes will be applied to ``master``, to the ``stable/1.6.x``
  129
+  branch, and to the ``stable/1.5.x`` branch. They will trigger the release of
134 130
   ``1.6.1``, ``1.5.1``, etc.
135 131
 
136 132
 * Documentation fixes will be applied to master, and, if easily backported, to
137  
-  the ``1.6.X`` branch. Bugfixes may also be backported.
  133
+  the ``1.6.x`` branch. Bugfixes may also be backported.
138 134
 
139 135
 .. _release-process:
140 136
 
@@ -193,9 +189,9 @@ Phase two will culminate with an alpha release. At this point, the
193 189
 Phase three: bugfixes
194 190
 ~~~~~~~~~~~~~~~~~~~~~
195 191
 
196  
-The last third of a release is spent fixing bugs -- no new features will be
197  
-accepted during this time. We'll try to release a beta release after one month
198  
-and a release candidate after two months.
  192
+The last third of a release cycle is spent fixing bugs -- no new features will
  193
+be accepted during this time. We'll try to release a beta release after one
  194
+month and a release candidate after two months.
199 195
 
200 196
 The release candidate marks the string freeze, and it happens at least two
201 197
 weeks before the final release. After this point, new translatable strings

0 notes on commit 01948e3

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