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
+the time of a new :term:`feature release`. We try to update them a second time
-of the following minor releases, but that depends on the translation manager's
+during one of the following :term:`patch release`\s, but that depends on the
-availability. So don't miss the string freeze period (between the release
+translation manager's availability. So don't miss the string freeze period
-candidate and the major release) to take the opportunity to complete and fix
+(between the release candidate and the feature release) to take the opportunity
-the translations for your language!
+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
+In each :term:`feature release`, all ``RemovedInDjangoXXWarning``\s matching
-version are removed.
+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
+  They are also used for bugfix and security releases which occur as necessary
-  after the initial release of a major or minor version.
+  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
+Django uses branches to prepare for releases of Django.
-:term:`major <Major release>` or :term:`minor <Minor release>`).
 
 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
+#. Create a stub release note for the new feature version. Use the stub from
-   previous major version or use the previous major version and delete most of
+   the previous feature release version or copy the contents from the previous
-   the contents leaving only section headings.
+   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
+* ``A.B`` is the *feature release* version number. Each version will be mostly
-  compatible with the previous release. Exceptions to this rule will be listed
+  backwards compatible with the previous release. Exceptions to this rule will
-  in the release notes. When ``B == 9``, the next major release will be
+  be listed in the release notes.
-  ``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
+* ``C`` is the *patch release* version number, which is incremented for bugfix
-  security fixes. A new minor release will be 100% backwards-compatible with
+  and security releases. These releases will be 100% backwards-compatible with
-  the previous minor release. The only exception is when a security or data loss
+  the previous patch release. The only exception is when a security or data
-  issue can't be fixed without breaking backwards-compatibility. If this
+  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
+  Feature release
-    Major releases (A.B, A.B+1, etc.) will happen roughly every nine months --
+    Feature releases (A.B, A.B+1, etc.) will happen roughly every eight months
-    see `release process`_, below for details. These releases will contain new
+    -- 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
+Deprecation policy
-    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 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
+* Django 4.2 will contain a backwards-compatible replica of the function which
-      will raise a ``RemovedInDjango19Warning``. This warning is silent by
+  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
+* Django 5.0 (the version that follows 4.2) will still contain the
-      warning becomes *loud* by default, and will likely be quite annoying.
+  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
+A more generic example:
-    Minor releases (A.B.C, etc.) will be issued as needed, often to fix security
-    issues.
 
-    These releases will be 100% compatible with the associated major release,
+* X.0
-    unless this is impossible for security reasons or to prevent data loss.
+* X.1
-    So the answer to "should I upgrade to the latest minor release?" will always
+* X.2 LTS
-    be "yes."
+* 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
+* Patches applied to the master branch must also be applied to the last feature
-  release, to be released as the next minor release, when they fix critical
+  release branch, to be released in the next patch release of that feature
-  problems:
+  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
+  The rule of thumb is that fixes will be backported to the last feature
-  for bugs that would have prevented a release in the first place (release
+  release for bugs that would have prevented a release in the first place
-  blockers).
+  (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
+* Critical bug fixes will be applied to the ``stable/5.1.x`` branch, and
-  released as 1.7.1, 1.7.2, etc.
+  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
+  ``master`` and to the ``stable/5.1.x``, and ``stable/4.2.x`` (LTS) branches.
-  ``stable/1.4.x`` (LTS) branches. They will trigger the release of ``1.7.1``,
+  They will trigger the release of ``5.1.1``, ``4.2.1``, etc.
-  ``1.6.1``, ``1.4.1``, etc.
 
 * Documentation fixes will be applied to master, and, if easily backported, to
-  the ``1.7.x`` and ``1.6.x`` branches.
+  the latest stable branch, ``5.1.x``.
-
-.. _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/
 
 .. _release-process:
 
 Release process
 ===============
 
-Django uses a time-based release schedule, with major (i.e. 1.8, 1.9, 2.0,
+Django uses a time-based release schedule, with feature releases every eight
-etc.) releases every nine months, or more, depending on features.
+months or so.
 
-After each release, and after a suitable cooling-off period of a few weeks,
+After each feature release, the release manager will announce a timeline for
-core developers will examine the landscape and announce a timeline for the
+the next feature release.
-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.
 
 Release cycle
 -------------
 
-Each release cycle will be split into three periods, each lasting roughly
+Each release cycle consists of three parts:
-one-third of the cycle:
 
 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
+Major features for an upcoming release will be added to the wiki roadmap page,
-upcoming release. This will be broken into:
+e.g. https://code.djangoproject.com/wiki/Version1.9Roadmap.
-
-* "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.
 
 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
+At the end of phase two, any unfinished features will be postponed until the
-phase.
+next release.
-
-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.
 
 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
+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 after one
+be accepted during this time. We'll try to release a beta release one month
-month and a release candidate after two months.
+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
+The branch for the previous feature release (e.g. ``stable/A.B-1.x``) will
-bugfixes. Critical bugs fixed on master must *also* be fixed on the bugfix
+include bugfixes. Critical bugs fixed on master must *also* be fixed on the
-branch; this means that commits need to cleanly separate bug fixes from feature
+bugfix branch; this means that commits need to cleanly separate bug fixes from
-additions. The developer who commits a fix to master will be responsible for
+feature additions. The developer who commits a fix to master will be
-also applying the fix to the current bugfix branch.
+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
+* :term:`Long-term support release`\s will receive security updates for a
-  security updates for a specified period.
+  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
+Django promises API stability and forwards-compatibility since version 1.0. In
-stability and forwards-compatibility. In a nutshell, this means that code you
+a nutshell, this means that code you develop against a version of Django will
-develop against a 1.X version of Django will continue to work with future
+continue to work with future releases. You may need to make minor changes when
-1.X releases. You may need to make minor changes when upgrading the version of
+upgrading the version of Django your project uses: see the "Backwards
-Django your project uses: see the "Backwards incompatible changes" section of
+incompatible changes" section of the :doc:`release note </releases/index>` for
-the :doc:`release note </releases/index>` for the version or versions to which
+the version or versions to which you are upgrading.
-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
+  feature releases. Warnings will be issued when the deprecated method is
-  is called.
+  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"
+Django 1.8 has been designated as Django's second :term:`long-term support
-(LTS) <lts-releases>` release. It will receive security updates for at least
+release`. It will receive security updates for at least three years after its
-three years after its release. Support for the previous LTS, Django 1.4, will
+release. Support for the previous LTS, Django 1.4, will end 6 months from the
-end 6 months from the release date of Django 1.8.
+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
+After a deprecation period of your choosing (two or three feature releases for
-Django itself), change the ``system_check_deprecated_details`` attribute to
+fields in Django itself), change the ``system_check_deprecated_details``
-``system_check_removed_details`` and update the dictionary similar to::
+attribute to ``system_check_removed_details`` and update the dictionary similar
+to::
 
     class IPAddressField(Field):
         system_check_removed_details = {