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