Skip to content

Commit

Permalink
Reorganize information about the branches of the repo. (python#411)
Browse files Browse the repository at this point in the history
  • Loading branch information
@ezio-melotti @willingc
ezio-melotti authored and willingc committed Sep 11, 2018
1 parent c6caa58 commit f8a3cb1
Show file tree
Hide file tree
Showing 4 changed files with 52 additions and 95 deletions.
4 changes: 2 additions & 2 deletions committing.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -228,7 +228,7 @@ repositories means you have to be more careful with your workflow:
* For a small change, you can make a quick edit through the GitHub web UI.
If you choose to use the web UI, be aware that GitHub will
create a new branch in the **main** CPython repo (not your fork). Please
delete this newly created branch after it has been merged into the
delete this newly created branch after it has been merged into the
``master`` branch or any of the maintenance branches. To keep the CPython
repo tidy, please try to limit the existence of the new branch to, at most,
a few days.
Expand All @@ -246,7 +246,7 @@ clone gets into a state you aren't happy with.
Active branches
'''''''''''''''

If you do ``git branch`` you will see a :ref:`list of branches <listbranch>`.
If you do ``git branch`` you will see a :ref:`list of branches <branchstatus>`.
``master`` is the in-development branch, and is the only branch that receives
new features. The other branches only receive bug fixes or security fixes.

Expand Down
35 changes: 13 additions & 22 deletions devcycle.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -26,6 +26,12 @@ We also publish non-final versions which get an additional qualifier:
:ref:`alpha`, :ref:`beta`, :ref:`release candidate <rc>`. These versions
are aimed at testing by advanced users, not production use.

Each release of Python is tagged in the source repo with a tag of the form
``vX.Y.ZTN``, where ``X`` is the major version, ``Y`` is the
minor version, ``Z`` is the micro version, ``T`` is the release level
(``a`` for alpha releases, ``b`` for beta, ``rc`` release candidate,
and *null* for final releases), and ``N`` is the release serial number.
Some examples of release tags: ``v3.7.0a1``, ``v3.6.3``, ``v2.7.14rc1``.

Branches
''''''''
Expand Down Expand Up @@ -100,33 +106,18 @@ You should also consider fixing hard-failing tests in open security branches
since it is important to be able to run the tests successfully before releasing.

Commits to security branches are to be coordinated with the release manager
for the corresponding feature version, as listed below in the Summary_.
for the corresponding feature version, as listed in the :ref:`branchstatus`.
Any release made from a security branch is source-only and done only when actual
security patches have been applied to the branch.


.. _listbranch:

Summary
-------

There are 6 open branches right now in the Git repository:

- the ``master`` branch accepts features and bugs fixes for the future
3.8.0 feature release (RM: Łukasz Langa)
- the ``3.7`` branch accepts bug and doc fixes for future 3.7.x maintenance
releases (RM: Ned Deily)
- the ``3.6`` branch accepts bug and doc fixes for future 3.6.x maintenance
releases (RM: Ned Deily)
- the ``3.5`` branch accepts security fixes for future 3.5.x security releases
(RM: Larry Hastings)
- the ``3.4`` branch accepts security fixes for future 3.4.x security releases
(RM: Larry Hastings)
- the ``2.7`` branch accepts bug and doc fixes for future 2.7.x maintenance
releases (RM: Benjamin Peterson)

See also the :ref:`Status of Python branches <branchstatus>`.
End-of-life branches
--------------------

The code base for a release cycle which has reached end-of-life status
is frozen and no longer has a branch in the repo. The final state of
the end-of-lifed branch is recorded as a tag with the same name as the
former branch, e.g. ``3.3`` or ``2.6``.

.. _stages:

Expand Down
16 changes: 8 additions & 8 deletions docquality.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -32,14 +32,14 @@ and validates that your new markup is correct.

You can view the documentation built from :ref:`in-development <indevbranch>`
and :ref:`maintenance <maintbranch>` branches at https://docs.python.org/dev/.
The in-development and most recent 3.x (as well as 2.x) maintenance
:ref:`branches <listbranch>` are rebuilt once per day.
The in-development and most recent 3.x (as well as 2.x) maintenance
branches are rebuilt once per day.

If you would like to be more involved with documentation, consider subscribing
to the `docs@python.org <https://mail.python.org/mailman/listinfo/docs>`_
mailing list. The `issue tracker`_ sends new documentation issues to this
mailing list. The `issue tracker`_ sends new documentation issues to this
mailing list, and, less frequently, the list receives some directly mailed bug
reports. The `docs-sig@python.org <https://mail.python.org/mailman/listinfo/doc-sig>`_
reports. The `docs-sig@python.org <https://mail.python.org/mailman/listinfo/doc-sig>`_
mailing list discusses the documentation toolchain, projects, and standards.


Expand All @@ -52,13 +52,13 @@ typos to unclear documentation and items lacking documentation.

If you see a documentation issue that you would like to tackle, you can:

* check to see if there is a paperclip or `octocat`_ icon at the end of the
* check to see if there is a paperclip or `octocat`_ icon at the end of the
issue's title column. If there is, then someone has already created a pull
request for the issue.
* leave a comment on the issue saying you are going to try and create a pull
request and roughly how long you think you will take to do so (this allows
* leave a comment on the issue saying you are going to try and create a pull
request and roughly how long you think you will take to do so (this allows
others to take on the issue if you happen to forget or lose interest).
* submit a :doc:`pull request <pullrequest>` for the issue.
* submit a :doc:`pull request <pullrequest>` for the issue.

By following the steps in the :ref:`Quick Guide to Pull Requests <pullrequest-quickguide>`,
you will learn the workflow for documentation pull requests.
Expand Down
92 changes: 29 additions & 63 deletions index.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@ Python Developer's Guide
.. highlight:: bash

This guide is a comprehensive resource for :ref:`contributing <contributing>`
to Python_ -- for both new and experienced contributors. It is
to Python_ -- for both new and experienced contributors. It is
:ref:`maintained <helping-with-the-developers-guide>` by the same
community that maintains Python. We welcome your contributions to Python!

Expand Down Expand Up @@ -89,33 +89,30 @@ contributing to Python:
Status of Python branches
-------------------------

+------------------+--------------+-------------+----------------+----------------+----------------------------------------------------------------------------+
| Branch | Schedule | Status | First release | End-of-life | Comment |
+==================+==============+=============+================+================+============================================================================+
| master | :pep:`569` | features | *2019-10-20* | *2024-10* | The master branch is currently the future Python 3.8. |
+------------------+--------------+-------------+----------------+----------------+----------------------------------------------------------------------------+
| 3.7 | :pep:`537` | bugfix | 2018-06-27 | *2023-06-27* | `Most recent binary release: Python 3.7.0 |
| | | | | | <https://www.python.org/downloads/release/python-370/>`_ |
+------------------+--------------+-------------+----------------+----------------+----------------------------------------------------------------------------+
| 3.6 | :pep:`494` | bugfix | 2016-12-23 | *2021-12-23* | `Most recent binary release: Python 3.6.6 |
| | | | | | <https://www.python.org/downloads/release/python-366/>`_ |
+------------------+--------------+-------------+----------------+----------------+----------------------------------------------------------------------------+
| 2.7 | :pep:`373` | bugfix | 2010-07-03 | *2020-01-01* | The support has been extended to 2020-01-01. |
| | | | | | `Most recent binary release: Python 2.7.15 |
| | | | | | <https://www.python.org/downloads/release/python-2715/>`_ |
+------------------+--------------+-------------+----------------+----------------+----------------------------------------------------------------------------+
| 3.5 | :pep:`478` | security | 2015-09-13 | *2020-09-13* | `Most recent security release: Python 3.5.5 |
| | | | | | <https://www.python.org/downloads/release/python-355/>`_ |
+------------------+--------------+-------------+----------------+----------------+----------------------------------------------------------------------------+
| 3.4 | :pep:`429` | security | 2014-03-16 | *2019-03-16* | `Most recent security release: Python 3.4.8 |
| | | | | | <https://www.python.org/downloads/release/python-348/>`_ |
+------------------+--------------+-------------+----------------+----------------+----------------------------------------------------------------------------+
+------------------+--------------+-------------+----------------+----------------+-------------------+
| Branch | Schedule | Status | First release | End-of-life | Release manager |
+==================+==============+=============+================+================+===================+
| master | :pep:`569` | features | *2019-10-20* | *2024-10* | Łukasz Langa |
+------------------+--------------+-------------+----------------+----------------+-------------------+
| 3.7 | :pep:`537` | bugfix | 2018-06-27 | *2023-06-27* | Ned Deily |
+------------------+--------------+-------------+----------------+----------------+-------------------+
| 3.6 | :pep:`494` | bugfix | 2016-12-23 | *2021-12-23* | Ned Deily |
+------------------+--------------+-------------+----------------+----------------+-------------------+
| 2.7 | :pep:`373` | bugfix | 2010-07-03 | *2020-01-01* | Benjamin Peterson |
+------------------+--------------+-------------+----------------+----------------+-------------------+
| 3.5 | :pep:`478` | security | 2015-09-13 | *2020-09-13* | Larry Hastings |
+------------------+--------------+-------------+----------------+----------------+-------------------+
| 3.4 | :pep:`429` | security | 2014-03-16 | *2019-03-16* | Larry Hastings |
+------------------+--------------+-------------+----------------+----------------+-------------------+

The master branch is currently the future Python 3.8, and is the only
branch that accepts new features. The latest release for each Python
version can be found on the `download page <https://www.python.org/downloads/>`_.

Status:

:features: new features are only added to the master branch, this branch
accepts any kind of change.
:prerelease: feature fixes, bugfixes and security fixes are accepted for the
:features: new features, bugfixes, and security fixes are accepted.
:prerelease: feature fixes, bugfixes, and security fixes are accepted for the
upcoming feature release.
:bugfix: bugfixes and security fixes are accepted, new binaries are still
released.
Expand All @@ -125,43 +122,12 @@ Status:

Dates in *italic* are scheduled and can be adjusted.

By default, the end-of-life is scheduled 5 years after the first release. It
can be adjusted by the release manager of each branch. Versions older than 2.7
have reached end-of-life.

See also :ref:`Security branches <secbranch>`.

Each release of Python is tagged in the source repo with a tag of the form
``vX.Y.ZTN``, where ``X`` is the major version, ``Y`` is the
minor version, ``Z`` is the micro version, ``T`` is the release level
(``a`` for alpha releases, ``b`` for beta, ``rc`` release candidate,
and *null* for final releases), and ``N`` is the release serial number.
Some examples of release tags: ``v3.7.0a1``, ``v3.6.3``, ``v2.7.14rc1``.

The code base for a release cycle which has reached end-of-life status
is frozen and no longer has a branch in the repo. The final state of
the end-of-lifed branch is recorded as a tag with the same name as the
former branch, e.g. ``3.3`` or ``2.6``. For reference, here are the
most recently end-of-lifed release cycles:

+------------------+--------------+-------------+----------------+----------------+----------------------------------------------------------------------------+
| Tag | Schedule | Status | First release | End-of-life | Comment |
+==================+==============+=============+================+================+============================================================================+
| 3.3 | :pep:`398` | end-of-life | 2012-09-29 | 2017-09-29 | `Final release: Python 3.3.7 |
| | | | | | <https://www.python.org/downloads/release/python-337/>`_ |
+------------------+--------------+-------------+----------------+----------------+----------------------------------------------------------------------------+
| 3.2 | :pep:`392` | end-of-life | 2011-02-20 | 2016-02-20 | `Final release: Python 3.2.6 |
| | | | | | <https://www.python.org/downloads/release/python-326/>`_ |
+------------------+--------------+-------------+----------------+----------------+----------------------------------------------------------------------------+
| 3.1 | :pep:`375` | end-of-life | 2009-06-27 | 2012-04-09 | `Final release: Python 3.1.5 |
| | | | | | <https://www.python.org/downloads/release/python-315/>`_ |
+------------------+--------------+-------------+----------------+----------------+----------------------------------------------------------------------------+
| 3.0 | :pep:`361` | end-of-life | 2008-12-03 | 2009-01-13 | `Final release: Python 3.0.1 |
| | | | | | <https://www.python.org/download/releases/3.0.1/>`_ |
+------------------+--------------+-------------+----------------+----------------+----------------------------------------------------------------------------+
| 2.6 | :pep:`361` | end-of-life | 2008-10-01 | 2013-10-29 | `Final release: Python 2.6.9 |
| | | | | | <https://www.python.org/download/releases/2.6.9/>`_ |
+------------------+--------------+-------------+----------------+----------------+----------------------------------------------------------------------------+
By default, the end-of-life is scheduled 5 years after the first release,
but can be adjusted by the release manager of each branch. The support for
Python 2.7 has currently been extended to 2020-01-01. Versions older than
2.7 have reached end-of-life.

See also the :ref:`devcycle` page for more information about branches.

.. _contributing:

Expand Down Expand Up @@ -210,7 +176,7 @@ Advanced tasks and topics for once you are comfortable:
See :ref:`how to review a Pull Request <how-to-review-a-pull-request>`.
* :doc:`fixingissues`

It is **recommended** that the above documents be read as needed. New
It is **recommended** that the above documents be read as needed. New
contributors will build understanding of the CPython workflow by reading the
sections mentioned in this table. You
can stop where you feel comfortable and begin contributing immediately without
Expand Down

0 comments on commit f8a3cb1

Please sign in to comment.