Adding upstream version 7.2.6.upstream/7.2.6

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 125 insertions, 0 deletions

diff --git a/doc/internals/release-process.rst b/doc/internals/release-process.rst
new file mode 100644
index 0000000..50648cd
--- /dev/null
+++ b/doc/internals/release-process.rst
@@ -0,0 +1,125 @@
+========================
+Sphinx's release process
+========================
+
+Versioning
+----------
+
+Sphinx adheres to :pep:`440` versions, with a ``major.minor.micro`` scheme for
+the *release segment* (e.g. 1.2.3).
+The major, minor, and micro version parts should be altered as follows:
+
+* The major version part should be incremented for incompatible behavior change and
+  public API updates.
+
+* The minor version part should be incremented for most releases of Sphinx, where
+  backwards-compatibility of API and features are preserves.
+
+* The micro version part should only be incremented for urgent bugfix-only releases.
+
+When the major version part is incremented, the minor and micro version parts
+must be set to ``0``.
+When the minor version part is incremented, the micro version part must be set
+to ``0``.
+
+New major versions should come with a beta-testing period before the final
+release.
+
+
+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.
+
+Python version support policy
+-----------------------------
+
+Sphinx supports at all minor versions of Python released in the past 42 months
+from the anticipated release date with a minimum of 3 minor versions of Python.
+This policy is derived from `NEP 29`_, a scientific Python domain standard.
+
+.. _NEP 29: https://numpy.org/neps/nep-0029-deprecation_policy.html
+
+For example, a version of Sphinx released in May 2024 would support Python 3.10,
+3.11, and 3.12.
+
+This is a summary table with the current policy:
+
+=========== ======
+Date        Python
+=========== ======
+26 Dec 2021 3.8+
+----------- ------
+14 Apr 2023 3.9+
+----------- ------
+05 Apr 2024 3.10+
+----------- ------
+04 Apr 2025 3.11+
+=========== ======
+
+Release procedures
+------------------
+
+The release procedures are listed in ``utils/release-checklist``.