You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
* 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.
Copy file name to clipboardExpand all lines: source/distributing.rst
+22-4Lines changed: 22 additions & 4 deletions
Original file line number
Diff line number
Diff line change
@@ -417,18 +417,30 @@ from the `setuptools docs <http://pythonhosted.org/setuptools/setuptools.html>`_
417
417
Choosing a versioning scheme
418
418
----------------------------
419
419
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::
422
427
423
428
1.2.0.dev1 # Development release
424
429
1.2.0a1 # Alpha Release
425
430
1.2.0b1 # Beta Release
426
431
1.2.0rc1 # Release Candidate
427
432
1.2.0 # Final Release
428
433
1.2.0.post1 # Post Release
434
+
15.10 # Date based release
435
+
23 # Serial release
429
436
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
+
*******************************
432
444
433
445
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.
434
446
@@ -447,6 +459,8 @@ Date based versioning
447
459
448
460
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.
449
461
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
+
450
464
Version numbers for date based projects typically take the form of YEAR.MONTH (for example, ``12.04``, ``15.10``).
451
465
452
466
Serial versioning
@@ -456,6 +470,10 @@ This is the simplest possible versioning scheme, and consists of a single number
456
470
457
471
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.
458
472
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.
0 commit comments