IntenseWebs/sphinx
3
0
Fork 0
mirror of https://github.com/sphinx-doc/sphinx.git synced 2025-02-25 18:55:22 -06:00
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #5938 from sphinx-doc/update-branch-model-for-semver

Browse Source 
Update deprecation policy by semantic versioning rules
This commit is contained in:
Takayuki SHIMIZUKAWA 2019-01-13 16:45:48 +09:00 committed by GitHub
commit ea134138b9
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 44 additions and 26 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

70
CONTRIBUTING.rst
View File

@ -61,8 +61,8 @@ of the core developers before it is merged into the main repository.
#. If you feel uncomfortable or uncertain about an issue or your changes, feel #. If you feel uncomfortable or uncertain about an issue or your changes, feel
free to email the *sphinx-dev* mailing list. free to email the *sphinx-dev* mailing list.
#. Fork `the repository`_ on GitHub to start making your changes to the #. Fork `the repository`_ on GitHub to start making your changes to the
``master`` branch for next major version, or ``X.Y`` branch for next ``master`` branch for next MAJOR version, or ``X.Y`` branch for next
minor version (see `Branch Model`_). MINOR version (see `Branch Model`_).
#. Write a test which shows that the bug was fixed or that the feature works #. Write a test which shows that the bug was fixed or that the feature works
as expected. as expected.
#. Send a pull request and bug the maintainer until it gets merged and #. Send a pull request and bug the maintainer until it gets merged and
@ -91,14 +91,19 @@ These are the basic steps needed to start developing on Sphinx.
#. Checkout the appropriate branch. #. Checkout the appropriate branch.
For changes that should be included in the next minor release (namely bug Sphinx adopts Semantic Versioning 2.0.0 (refs: https://semver.org/ ).
fixes), use the ``X.Y`` branch. ::
For changes that preserves backwards-compatibility of API and features,
they should be included in the next MINOR release, use the ``X.Y`` branch.
::
git checkout X.Y git checkout X.Y
For new features or other substantial changes that should wait until the For incompatible or other substantial changes that should wait until the
next major release, use the ``master`` branch (see `Branch Model`_ for next MAJOR release, use the ``master`` branch.
detail).
For urgent release, a new PATCH branch must be branched from the newest
release tag (see `Branch Model`_ for detail).
#. Setup a virtual environment. #. Setup a virtual environment.
@ -312,18 +317,32 @@ Debugging Tips
Branch Model Branch Model
------------ ------------
Sphinx project uses following branches for developing. Sphinx project uses following branches for developing that conforms to Semantic
Versioning 2.0.0 (refs: https://semver.org/ ).
``master`` ``master``
Used for main development. All improvement and refactoring, bug fixes Development for MAJOR version.
are allowed. All changes including incompatible behaviors and public API updates are
allowed.
``X.Y`` ``X.Y``
Where ``X.Y`` is the ``MAJOR.MINOR`` release. Used to maintain current Where ``X.Y`` is the ``MAJOR.MINOR`` release. Used to maintain current
stable release. Only bug fixes and stable changes are allowed. Only the MINOR release. All changes are allowed if the change preserves
most recent stable release is currently retained. When a new version is backwards-compatibility of API and features.
released, the old release branch will be deleted and replaced by an
equivalent tag. 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.
``X.Y.Z``
Where ``X.Y.Z`` 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 Deprecating a feature
@ -356,23 +375,22 @@ silence any warnings generated when running the tests.
Deprecation policy Deprecation policy
------------------ ------------------
A feature release may deprecate certain features from previous releases. If a MAJOR and MINOR releases may deprecate certain features from previous
feature is deprecated in feature release 1.A, it will continue to work in all releases. If a feature is deprecated in a release A.x, it will continue to
1.A.x versions (for all versions of x) but raise warnings. Deprecated features work in all A.x.x versions (for all versions of x). It will continue to work
will be removed in the first 1.B release, or 1.B.1 for features deprecated in in all B.x.x versions but raise deprecation warnings. Deprecated features
the last 1.A.x feature release to ensure deprecations are done over at least 2 will be removed at the C.0.0. It means the deprecated feature will work during
feature releases. 2 MAJOR releases at least.
So, for example, if we decided to start the deprecation of a function in So, for example, if we decided to start the deprecation of a function in
Sphinx 1.4: Sphinx 2.x:
* Sphinx 1.4.x will contain a backwards-compatible replica of the function * Sphinx 2.x will contain a backwards-compatible replica of the function
which will raise a ``RemovedInSphinx16Warning``. which will raise a ``RemovedInSphinx40Warning``.
* Sphinx 1.5 (the version that follows 1.4) will still contain the * Sphinx 3.x will still contain the backwards-compatible replica.
backwards-compatible replica.
* Sphinx 1.6 will remove the feature outright. * Sphinx 4.0 will remove the feature outright.
The warnings are displayed by default. You can turn off display of these The warnings are displayed by default. You can turn off display of these
warnings with: warnings with: