Updated release process for new release schedule.

docs/internals/contributing/localizing.txt

@@ -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
 -------

docs/internals/contributing/writing-code/submitting-patches.txt

@@ -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
 ------------------

docs/internals/contributing/writing-documentation.txt

@@ -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`
 

docs/internals/git.txt

@@ -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

docs/internals/howto-release-django.txt

@@ -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%

docs/internals/organization.txt

@@ -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:
 

docs/internals/release-process.txt

@@ -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.
-
-* ``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
+* ``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 *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.
 
-    .. _internal-release-deprecation-policy:
+  Patch release
+    Patch releases (A.B.C, A.B.C+1, etc.) will be issued as needed, to fix
+    bugs and/or security issues.
 
-    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``.
+    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.
 
-    So, for example, if we decided to start the deprecation of a function in
-    Django 1.7:
+    See `the download page`_ for the releases that have been designated for
+    long-term support.
 
-    * 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.
+    .. _the download page: https://www.djangoproject.com/download/
 
-    * Django 1.8 will still contain the backwards-compatible replica. This
-      warning becomes *loud* by default, and will likely be quite annoying.
+Release cadence
+===============
 
-    * Django 1.9 will remove the feature outright.
+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.
 
-  Minor release
-    Minor releases (A.B.C, etc.) will be issued as needed, often to fix security
-    issues.
+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.
 
-    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."
+.. _internal-release-deprecation-policy:
+
+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 4.2:
+
+* 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 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 5.1 will remove the feature outright.
+
+A more generic example:
+
+* 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.

docs/internals/security.txt

@@ -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

docs/misc/api-stability.txt

@@ -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.

docs/releases/1.8.txt

@@ -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`_

docs/releases/index.txt

@@ -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:

docs/topics/migrations.txt

@@ -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 = {