mirror of
https://github.com/sphinx-doc/sphinx.git
synced 2025-02-25 18:55:22 -06:00
docs: Add release process document
This is based on content extracted from the CONTRIBUTING document. Signed-off-by: Stephen Finucane <stephen@that.guru>
This commit is contained in:
Stephen Finucane
parent
6b19678253
commit
a33483f154
102
CONTRIBUTING.rst
102
CONTRIBUTING.rst
@ -62,7 +62,7 @@ of the core developers before it is merged into the main repository.
|
||||
free to email the *sphinx-dev* mailing list.
|
||||
#. Fork `the repository`_ on GitHub to start making your changes to the
|
||||
``master`` branch for next MAJOR version, or ``A.x`` branch for next
|
||||
MINOR version (see `Branch Model`_).
|
||||
MINOR version (see :doc:`/internals/release-process`).
|
||||
#. Write a test which shows that the bug was fixed or that the feature works
|
||||
as expected.
|
||||
#. Send a pull request and bug the maintainer until it gets merged and
|
||||
@ -103,7 +103,7 @@ These are the basic steps needed to start developing on Sphinx.
|
||||
next MAJOR release, use the ``master`` branch.
|
||||
|
||||
For urgent release, a new PATCH branch must be branched from the newest
|
||||
release tag (see `Branch Model`_ for detail).
|
||||
release tag (see :doc:`/internals/release-process` for detail).
|
||||
|
||||
#. Setup a virtual environment.
|
||||
|
||||
@ -265,104 +265,6 @@ Debugging Tips
|
||||
node_modules/.bin/grunt build # -> dest/*.global.js
|
||||
|
||||
|
||||
Branch Model
|
||||
------------
|
||||
|
||||
Sphinx project uses following branches for developing that conforms to Semantic
|
||||
Versioning 2.0.0 (refs: https://semver.org/ ).
|
||||
|
||||
``master``
|
||||
Development for MAJOR version.
|
||||
All changes including incompatible behaviors and public API updates are
|
||||
allowed.
|
||||
|
||||
``A.x`` (ex. ``2.x``)
|
||||
Where ``A.x`` is the ``MAJOR.MINOR`` release. Used to maintain current
|
||||
MINOR release. All changes are allowed if the change preserves
|
||||
backwards-compatibility of API and features.
|
||||
|
||||
Only the most recent ``MAJOR.MINOR`` branch is currently retained. When a
|
||||
new MAJOR version is released, the old ``MAJOR.MINOR`` branch will be
|
||||
deleted and replaced by an equivalent tag.
|
||||
|
||||
``A.B.x`` (ex. ``2.4.x``)
|
||||
Where ``A.B.x`` is the ``MAJOR.MINOR.PATCH`` release. Only
|
||||
backwards-compatible bug fixes are allowed. In Sphinx project, PATCH
|
||||
version is used for urgent bug fix.
|
||||
|
||||
``MAJOR.MINOR.PATCH`` branch will be branched from the ``v`` prefixed
|
||||
release tag (ex. make 2.3.1 that branched from v2.3.0) when a urgent
|
||||
release is needed. When new PATCH version is released, the branch will be
|
||||
deleted and replaced by an equivalent tag (ex. v2.3.1).
|
||||
|
||||
|
||||
Deprecating a feature
|
||||
---------------------
|
||||
|
||||
There are a couple reasons that code in Sphinx might be deprecated:
|
||||
|
||||
* If a feature has been improved or modified in a backwards-incompatible way,
|
||||
the old feature or behavior will be deprecated.
|
||||
|
||||
* Sometimes Sphinx will include a backport of a Python library that's not
|
||||
included in a version of Python that Sphinx currently supports. When Sphinx
|
||||
no longer needs to support the older version of Python that doesn't include
|
||||
the library, the library will be deprecated in Sphinx.
|
||||
|
||||
As the :ref:`deprecation-policy` describes, the first release of Sphinx that
|
||||
deprecates a feature (``A.B``) should raise a ``RemovedInSphinxXXWarning``
|
||||
(where ``XX`` is the Sphinx version where the feature will be removed) when the
|
||||
deprecated feature is invoked. Assuming we have good test coverage, these
|
||||
warnings are converted to errors when running the test suite with warnings
|
||||
enabled::
|
||||
|
||||
pytest -Wall
|
||||
|
||||
Thus, when adding a ``RemovedInSphinxXXWarning`` you need to eliminate or
|
||||
silence any warnings generated when running the tests.
|
||||
|
||||
.. _deprecation-policy:
|
||||
|
||||
Deprecation policy
|
||||
------------------
|
||||
|
||||
MAJOR and MINOR releases may deprecate certain features from previous
|
||||
releases. If a feature is deprecated in a release A.x, it will continue to
|
||||
work in all A.x.x versions (for all versions of x). It will continue to work
|
||||
in all B.x.x versions but raise deprecation warnings. Deprecated features
|
||||
will be removed at the C.0.0. It means the deprecated feature will work during
|
||||
2 MAJOR releases at least.
|
||||
|
||||
So, for example, if we decided to start the deprecation of a function in
|
||||
Sphinx 2.x:
|
||||
|
||||
* Sphinx 2.x will contain a backwards-compatible replica of the function
|
||||
which will raise a ``RemovedInSphinx40Warning``.
|
||||
This is a subclass of :exc:`python:PendingDeprecationWarning`, i.e. it
|
||||
will not get displayed by default.
|
||||
|
||||
* Sphinx 3.x will still contain the backwards-compatible replica, but
|
||||
``RemovedInSphinx40Warning`` will be a subclass of
|
||||
:exc:`python:DeprecationWarning` then, and gets displayed by default.
|
||||
|
||||
* Sphinx 4.0 will remove the feature outright.
|
||||
|
||||
Deprecation warnings
|
||||
~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
Sphinx will enable its ``RemovedInNextVersionWarning`` warnings by default,
|
||||
if :envvar:`python:PYTHONWARNINGS` is not set.
|
||||
Therefore you can disable them using:
|
||||
|
||||
* ``PYTHONWARNINGS= make html`` (Linux/Mac)
|
||||
* ``export PYTHONWARNINGS=`` and do ``make html`` (Linux/Mac)
|
||||
* ``set PYTHONWARNINGS=`` and do ``make html`` (Windows)
|
||||
|
||||
But you can also explicitly enable the pending ones using e.g.
|
||||
``PYTHONWARNINGS=default`` (see the
|
||||
:ref:`Python docs on configuring warnings <python:describing-warning-filters>`)
|
||||
for more details.
|
||||
|
||||
Unit Testing
|
||||
------------
|
||||
|
||||
|
||||
@ -9,6 +9,7 @@ how to contribute to the project.
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
|
||||
release-process
|
||||
organization
|
||||
code-of-conduct
|
||||
authors
|
||||
|
||||
106
doc/internals/release-process.rst
Normal file
106
doc/internals/release-process.rst
Normal file
@ -0,0 +1,106 @@
|
||||
========================
|
||||
Sphinx's release process
|
||||
========================
|
||||
|
||||
Branch Model
|
||||
------------
|
||||
|
||||
Sphinx project uses following branches for developing that conforms to Semantic
|
||||
Versioning 2.0.0 (refs: https://semver.org/ ).
|
||||
|
||||
``master``
|
||||
Development for MAJOR version.
|
||||
All changes including incompatible behaviors and public API updates are
|
||||
allowed.
|
||||
|
||||
``A.x`` (ex. ``2.x``)
|
||||
Where ``A.x`` is the ``MAJOR.MINOR`` release. Used to maintain current
|
||||
MINOR release. All changes are allowed if the change preserves
|
||||
backwards-compatibility of API and features.
|
||||
|
||||
Only the most recent ``MAJOR.MINOR`` branch is currently retained. When a
|
||||
new MAJOR version is released, the old ``MAJOR.MINOR`` branch will be
|
||||
deleted and replaced by an equivalent tag.
|
||||
|
||||
``A.B.x`` (ex. ``2.4.x``)
|
||||
Where ``A.B.x`` is the ``MAJOR.MINOR.PATCH`` release. Only
|
||||
backwards-compatible bug fixes are allowed. In Sphinx project, PATCH
|
||||
version is used for urgent bug fix.
|
||||
|
||||
``MAJOR.MINOR.PATCH`` branch will be branched from the ``v`` prefixed
|
||||
release tag (ex. make 2.3.1 that branched from v2.3.0) when a urgent
|
||||
release is needed. When new PATCH version is released, the branch will be
|
||||
deleted and replaced by an equivalent tag (ex. v2.3.1).
|
||||
|
||||
|
||||
Deprecating a feature
|
||||
---------------------
|
||||
|
||||
There are a couple reasons that code in Sphinx might be deprecated:
|
||||
|
||||
* If a feature has been improved or modified in a backwards-incompatible way,
|
||||
the old feature or behavior will be deprecated.
|
||||
|
||||
* Sometimes Sphinx will include a backport of a Python library that's not
|
||||
included in a version of Python that Sphinx currently supports. When Sphinx
|
||||
no longer needs to support the older version of Python that doesn't include
|
||||
the library, the library will be deprecated in Sphinx.
|
||||
|
||||
As the :ref:`deprecation-policy` describes, the first release of Sphinx that
|
||||
deprecates a feature (``A.B``) should raise a ``RemovedInSphinxXXWarning``
|
||||
(where ``XX`` is the Sphinx version where the feature will be removed) when the
|
||||
deprecated feature is invoked. Assuming we have good test coverage, these
|
||||
warnings are converted to errors when running the test suite with warnings
|
||||
enabled::
|
||||
|
||||
pytest -Wall
|
||||
|
||||
Thus, when adding a ``RemovedInSphinxXXWarning`` you need to eliminate or
|
||||
silence any warnings generated when running the tests.
|
||||
|
||||
|
||||
.. _deprecation-policy:
|
||||
|
||||
Deprecation policy
|
||||
------------------
|
||||
|
||||
MAJOR and MINOR releases may deprecate certain features from previous
|
||||
releases. If a feature is deprecated in a release A.x, it will continue to
|
||||
work in all A.x.x versions (for all versions of x). It will continue to work
|
||||
in all B.x.x versions but raise deprecation warnings. Deprecated features
|
||||
will be removed at the C.0.0. It means the deprecated feature will work during
|
||||
2 MAJOR releases at least.
|
||||
|
||||
So, for example, if we decided to start the deprecation of a function in
|
||||
Sphinx 2.x:
|
||||
|
||||
* Sphinx 2.x will contain a backwards-compatible replica of the function
|
||||
which will raise a ``RemovedInSphinx40Warning``.
|
||||
This is a subclass of :exc:`python:PendingDeprecationWarning`, i.e. it
|
||||
will not get displayed by default.
|
||||
|
||||
* Sphinx 3.x will still contain the backwards-compatible replica, but
|
||||
``RemovedInSphinx40Warning`` will be a subclass of
|
||||
:exc:`python:DeprecationWarning` then, and gets displayed by default.
|
||||
|
||||
* Sphinx 4.0 will remove the feature outright.
|
||||
|
||||
Deprecation warnings
|
||||
~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
Sphinx will enable its ``RemovedInNextVersionWarning`` warnings by default, if
|
||||
:envvar:`python:PYTHONWARNINGS` is not set. Therefore you can disable them
|
||||
using:
|
||||
|
||||
* ``PYTHONWARNINGS= make html`` (Linux/Mac)
|
||||
* ``export PYTHONWARNINGS=`` and do ``make html`` (Linux/Mac)
|
||||
* ``set PYTHONWARNINGS=`` and do ``make html`` (Windows)
|
||||
|
||||
But you can also explicitly enable the pending ones using e.g.
|
||||
``PYTHONWARNINGS=default`` (see the :ref:`Python docs on configuring warnings
|
||||
<python:describing-warning-filters>`) for more details.
|
||||
|
||||
Release procedures
|
||||
------------------
|
||||
|
||||
The release procedures are listed in ``utils/release-checklist``.
|
||||
Loading…
Reference in New Issue
Block a user