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
Copy file name to clipboardExpand all lines: source/distributing.rst
+48-17Lines changed: 48 additions & 17 deletions
Original file line number
Diff line number
Diff line change
@@ -420,8 +420,11 @@ Choosing a versioning scheme
420
420
Standards compliance for interoperability
421
421
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
422
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``.
423
+
Different Python projects may use different versioning schemes based on the needs of that
424
+
particular project, but all of them are required to comply with the flexible `public version
in :ref:`PEP440 <pypa:PEP440s>` in order to be supported in tools and libraries like ``pip``
427
+
and ``setuptools``.
425
428
426
429
Here are some examples of compliant version numbers::
427
430
@@ -434,66 +437,94 @@ Here are some examples of compliant version numbers::
434
437
15.10 # Date based release
435
438
23 # Serial release
436
439
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.
440
+
To further accommodate historical variations in approaches to version numbering,
441
+
:ref:`PEP440 <pypa:PEP440s>` also defines a comprehensive technique for `version
442
+
normalisation <https://www.python.org/dev/peps/pep-0440/#normalization>`_ that maps
443
+
variant spellings of different version numbers to a standardised canonical form.
438
444
439
445
Scheme choices
440
446
~~~~~~~~~~~~~~
441
447
442
448
Semantic versioning (preferred)
443
449
*******************************
444
450
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.
451
+
For new projects, the recommended versioning scheme is based on `Semantic Versioning
452
+
<http://semver.org>`_, but adopts a different approach to handling pre-releases and
453
+
build metadata.
446
454
447
-
The essence of semantic versioning is a 3-part MAJOR.MINOR.MAINTENANCE numbering scheme, where the project author increments:
455
+
The essence of semantic versioning is a 3-part MAJOR.MINOR.MAINTENANCE numbering scheme,
456
+
where the project author increments:
448
457
449
458
1. MAJOR version when they make incompatible API changes,
450
459
2. MINOR version when they add functionality in a backwards-compatible manner, and
451
460
3. MAINTENANCE version when they make backwards-compatible bug fixes.
452
461
453
-
Adopting this approach as a project author allows users to make use of `"compatible release" <https://www.python.org/dev/peps/pep-0440/#compatible-release>`_ specifiers, where ``name ~= X.Y`` requires at least release X.Y, but also allows any later release with a matching MAJOR version.
462
+
Adopting this approach as a project author allows users to make use of `"compatible release"
463
+
<https://www.python.org/dev/peps/pep-0440/#compatible-release>`_ specifiers, where
464
+
``name ~= X.Y`` requires at least release X.Y, but also allows any later release with
465
+
a matching MAJOR version.
454
466
455
-
Python projects adopting semantic versioning should abide by clauses 1-8 of the `Semantic Versioning 2.0.0 specification <http://semver.org>`_.
467
+
Python projects adopting semantic versioning should abide by clauses 1-8 of the
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.
473
+
Semantic versioning is not a suitable choice for all projects, such as those with a regular
474
+
time based release cadence and a deprecation process that provides warnings for a number of
475
+
releases prior to removal of a feature.
461
476
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.
477
+
A key advantage of date based versioning is that it is straightforward to tell how old the
478
+
base feature set of a particular release is given just the version number.
463
479
464
-
Version numbers for date based projects typically take the form of YEAR.MONTH (for example, ``12.04``, ``15.10``).
480
+
Version numbers for date based projects typically take the form of YEAR.MONTH (for example,
481
+
``12.04``, ``15.10``).
465
482
466
483
Serial versioning
467
484
*****************
468
485
469
-
This is the simplest possible versioning scheme, and consists of a single number which is incremented every release.
486
+
This is the simplest possible versioning scheme, and consists of a single number which is
487
+
incremented every release.
470
488
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.
489
+
While serial versioning is very easy to manage as a developer, it is the hardest to track
490
+
as an end user, as serial version numbers convey little or no information regarding API
491
+
backwards compatibility.
472
492
473
493
Hybrid schemes
474
494
**************
475
495
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.
496
+
Combinations of the above schemes are possible. For example, a project may combine date
497
+
based versioning with serial versioning to create a YEAR.SERIAL numbering scheme that
498
+
readily conveys the approximate age of a release, but doesn't otherwise commit to a particular
499
+
release cadence within the year.
477
500
478
501
Pre-release versioning
479
502
~~~~~~~~~~~~~~~~~~~~~~
480
503
481
-
Regardless of the base versioning scheme, pre-releases for a given final release may be published as:
504
+
Regardless of the base versioning scheme, pre-releases for a given final release may be
505
+
published as:
482
506
483
507
* zero or more dev releases (denoted with a ".devN" suffix)
484
508
* zero or more alpha releases (denoted with a ".aN" suffix)
485
509
* zero or more beta releases (denoted with a ".bN" suffix)
486
510
* zero or more release candidates (denoted with a ".rcN" suffix)
487
511
488
-
``pip`` and other modern Python package installers ignore pre-releases by default when deciding which versions of dependencies to install.
512
+
``pip`` and other modern Python package installers ignore pre-releases by default when
513
+
deciding which versions of dependencies to install.
489
514
490
515
491
516
Local version identifiers
492
517
~~~~~~~~~~~~~~~~~~~~~~~~~
493
518
494
-
Public version identifiers are designed to support distribution via :term:`PyPI <Python Package Index (PyPI)>`. Python's software distribution tools also support the notion of a `local version identifier <https://www.python.org/dev/peps/pep-0440/#local-version-identifiers>`_, which can be used to identify local development builds not intended for publication, or modified variants of a release maintained by a redistributor.
519
+
Public version identifiers are designed to support distribution via
520
+
:term:`PyPI <Python Package Index (PyPI)>`. Python's software distribution tools also support
521
+
the notion of a `local version identifier
522
+
<https://www.python.org/dev/peps/pep-0440/#local-version-identifiers>`_, which can be used to
523
+
identify local development builds not intended for publication, or modified variants of a release
524
+
maintained by a redistributor.
495
525
496
-
A local version identifier takes the form ``<public version identifier>+<local version label>``. For example::
526
+
A local version identifier takes the form ``<public version identifier>+<local version label>``.
527
+
For example::
497
528
498
529
1.2.0.dev1+hg.5.b11e5e6f0b0b # 5th VCS commmit since 1.2.0.dev1 release
499
530
1.2.1+fedora.4 # Package with downstream Fedora patches applied
0 commit comments