Skip to content

Commit 387e670

Browse files
committed
Address feedback from Marcus Smith
* Standards compliance gets its own subheading * Semantic versioning gets its own subheading I also added a new section on hybrid versioning schemes (mainly to capture YEAR.SERIAL as pattern), and a discussion of version normalisation in the section on standards compliance.
1 parent 0646aaa commit 387e670

File tree

1 file changed

+22
-4
lines changed

1 file changed

+22
-4
lines changed

source/distributing.rst

Lines changed: 22 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -417,18 +417,30 @@ from the `setuptools docs <http://pythonhosted.org/setuptools/setuptools.html>`_
417417
Choosing a versioning scheme
418418
----------------------------
419419

420-
Different Python projects may use different versioning schemes, but all of them will comply with the `public version scheme
421-
<https://www.python.org/dev/peps/pep-0440/#public-version-identifiers>`_ specified in :ref:`PEP440 <pypa:PEP440s>`. Here are some examples of compliant version numbers::
420+
Standards compliance for interoperability
421+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
422+
423+
Different Python projects may use different versioning schemes based on the needs of that particular project, but all of them are required to comply with the flexible `public version scheme
424+
<https://www.python.org/dev/peps/pep-0440/#public-version-identifiers>`_ specified in :ref:`PEP440 <pypa:PEP440s>` in order to be supported in tools and libraries like ``pip`` and ``setuptools``.
425+
426+
Here are some examples of compliant version numbers::
422427

423428
1.2.0.dev1 # Development release
424429
1.2.0a1 # Alpha Release
425430
1.2.0b1 # Beta Release
426431
1.2.0rc1 # Release Candidate
427432
1.2.0 # Final Release
428433
1.2.0.post1 # Post Release
434+
15.10 # Date based release
435+
23 # Serial release
429436

430-
Recommended versioning scheme
431-
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
437+
To further accommodate historical variations in approaches to version numbering, :ref:`PEP440 <pypa:PEP440s>` also defines a comprehensive technique for `version normalisation <https://www.python.org/dev/peps/pep-0440/#normalization>`_ that maps variant spellings of different version numbers to a standardised canonical form.
438+
439+
Scheme choices
440+
~~~~~~~~~~~~~~
441+
442+
Semantic versioning (preferred)
443+
*******************************
432444

433445
For new projects, the recommended versioning scheme is based on `Semantic Versioning <http://semver.org>`_, but adopts a different approach to handling pre-releases and build metadata.
434446

@@ -447,6 +459,8 @@ Date based versioning
447459

448460
Semantic versioning is not a suitable choice for all projects, such as those with a regular time based release cadence and a deprecation process that provides warnings for a number of releases prior to removal of a feature.
449461

462+
A key advantage of date based versioning is that it is straightforward to tell how old the base feature set of a particular release is given just the version number.
463+
450464
Version numbers for date based projects typically take the form of YEAR.MONTH (for example, ``12.04``, ``15.10``).
451465

452466
Serial versioning
@@ -456,6 +470,10 @@ This is the simplest possible versioning scheme, and consists of a single number
456470

457471
While serial versioning is very easy to manage as a developer, it is the hardest to track as an end user, as serial version numbers convey little or no information regarding API backwards compatibility.
458472

473+
Hybrid schemes
474+
**************
475+
476+
Combinations of the above schemes are possible. For example, a project may combine data based versioning with serial versioning to create a YEAR.SERIAL numbering scheme that readily conveys the approximate age of a release, but doesn't otherwise commit to a particular release cadence within the year.
459477

460478
Pre-release versioning
461479
~~~~~~~~~~~~~~~~~~~~~~

0 commit comments

Comments
 (0)