1========================
2Sphinx's release process
3========================
4
5Branch Model
6------------
7
8Sphinx project uses following branches for developing that conforms to Semantic
9Versioning 2.0.0 (refs: https://semver.org/ ).
10
11``master``
12    Development for MAJOR version.
13    All changes including incompatible behaviors and public API updates are
14    allowed.
15
16``A.x`` (ex. ``2.x``)
17    Where ``A.x`` is the ``MAJOR.MINOR`` release.  Used to maintain current
18    MINOR release. All changes are allowed if the change preserves
19    backwards-compatibility of API and features.
20
21    Only the most recent ``MAJOR.MINOR`` branch is currently retained. When a
22    new MAJOR version is released, the old ``MAJOR.MINOR`` branch will be
23    deleted and replaced by an equivalent tag.
24
25``A.B.x`` (ex. ``2.4.x``)
26    Where ``A.B.x`` is the ``MAJOR.MINOR.PATCH`` release.  Only
27    backwards-compatible bug fixes are allowed. In Sphinx project, PATCH
28    version is used for urgent bug fix.
29
30    ``MAJOR.MINOR.PATCH`` branch will be branched from the ``v`` prefixed
31    release tag (ex. make 2.3.1 that branched from v2.3.0) when a urgent
32    release is needed. When new PATCH version is released, the branch will be
33    deleted and replaced by an equivalent tag (ex. v2.3.1).
34
35
36Deprecating a feature
37---------------------
38
39There are a couple reasons that code in Sphinx might be deprecated:
40
41* If a feature has been improved or modified in a backwards-incompatible way,
42  the old feature or behavior will be deprecated.
43
44* Sometimes Sphinx will include a backport of a Python library that's not
45  included in a version of Python that Sphinx currently supports. When Sphinx
46  no longer needs to support the older version of Python that doesn't include
47  the library, the library will be deprecated in Sphinx.
48
49As the :ref:`deprecation-policy` describes, the first release of Sphinx that
50deprecates a feature (``A.B``) should raise a ``RemovedInSphinxXXWarning``
51(where ``XX`` is the Sphinx version where the feature will be removed) when the
52deprecated feature is invoked. Assuming we have good test coverage, these
53warnings are converted to errors when running the test suite with warnings
54enabled::
55
56    pytest -Wall
57
58Thus, when adding a ``RemovedInSphinxXXWarning`` you need to eliminate or
59silence any warnings generated when running the tests.
60
61
62.. _deprecation-policy:
63
64Deprecation policy
65------------------
66
67MAJOR and MINOR releases may deprecate certain features from previous
68releases. If a feature is deprecated in a release A.x, it will continue to
69work in all A.x.x versions (for all versions of x). It will continue to work
70in all B.x.x versions but raise deprecation warnings. Deprecated features
71will be removed at the C.0.0. It means the deprecated feature will work during
722 MAJOR releases at least.
73
74So, for example, if we decided to start the deprecation of a function in
75Sphinx 2.x:
76
77* Sphinx 2.x will contain a backwards-compatible replica of the function
78  which will raise a ``RemovedInSphinx40Warning``.
79  This is a subclass of :exc:`python:PendingDeprecationWarning`, i.e. it
80  will not get displayed by default.
81
82* Sphinx 3.x will still contain the backwards-compatible replica, but
83  ``RemovedInSphinx40Warning`` will be a subclass of
84  :exc:`python:DeprecationWarning` then, and gets displayed by default.
85
86* Sphinx 4.0 will remove the feature outright.
87
88Deprecation warnings
89~~~~~~~~~~~~~~~~~~~~
90
91Sphinx will enable its ``RemovedInNextVersionWarning`` warnings by default, if
92:envvar:`python:PYTHONWARNINGS` is not set.  Therefore you can disable them
93using:
94
95* ``PYTHONWARNINGS= make html`` (Linux/Mac)
96* ``export PYTHONWARNINGS=`` and do ``make html`` (Linux/Mac)
97* ``set PYTHONWARNINGS=`` and do ``make html`` (Windows)
98
99But you can also explicitly enable the pending ones using e.g.
100``PYTHONWARNINGS=default`` (see the :ref:`Python docs on configuring warnings
101<python:describing-warning-filters>`) for more details.
102
103Release procedures
104------------------
105
106The release procedures are listed in ``utils/release-checklist``.
107