Skip to content

Commit 391c903

Browse files
committed
Line wrapping & typos
Just noticed that I was relying on the soft wrap in GitHub's online editor rather than explicitly wrapping the lines.
1 parent 387e670 commit 391c903

File tree

1 file changed

+48
-17
lines changed

1 file changed

+48
-17
lines changed

source/distributing.rst

Lines changed: 48 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -420,8 +420,11 @@ Choosing a versioning scheme
420420
Standards compliance for interoperability
421421
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
422422

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
425+
scheme <https://www.python.org/dev/peps/pep-0440/#public-version-identifiers>`_ specified
426+
in :ref:`PEP440 <pypa:PEP440s>` in order to be supported in tools and libraries like ``pip``
427+
and ``setuptools``.
425428

426429
Here are some examples of compliant version numbers::
427430

@@ -434,66 +437,94 @@ Here are some examples of compliant version numbers::
434437
15.10 # Date based release
435438
23 # Serial release
436439

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.
438444

439445
Scheme choices
440446
~~~~~~~~~~~~~~
441447

442448
Semantic versioning (preferred)
443449
*******************************
444450

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.
446454

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:
448457

449458
1. MAJOR version when they make incompatible API changes,
450459
2. MINOR version when they add functionality in a backwards-compatible manner, and
451460
3. MAINTENANCE version when they make backwards-compatible bug fixes.
452461

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.
454466

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
468+
`Semantic Versioning 2.0.0 specification <http://semver.org>`_.
456469

457470
Date based versioning
458471
*********************
459472

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.
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.
461476

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.
463479

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``).
465482

466483
Serial versioning
467484
*****************
468485

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.
470488

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.
472492

473493
Hybrid schemes
474494
**************
475495

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.
477500

478501
Pre-release versioning
479502
~~~~~~~~~~~~~~~~~~~~~~
480503

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:
482506

483507
* zero or more dev releases (denoted with a ".devN" suffix)
484508
* zero or more alpha releases (denoted with a ".aN" suffix)
485509
* zero or more beta releases (denoted with a ".bN" suffix)
486510
* zero or more release candidates (denoted with a ".rcN" suffix)
487511

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.
489514

490515

491516
Local version identifiers
492517
~~~~~~~~~~~~~~~~~~~~~~~~~
493518

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.
495525

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::
497528

498529
1.2.0.dev1+hg.5.b11e5e6f0b0b # 5th VCS commmit since 1.2.0.dev1 release
499530
1.2.1+fedora.4 # Package with downstream Fedora patches applied

0 commit comments

Comments
 (0)