diff options
| author | Jason R. Coombs <jaraco@jaraco.com> | 2021-09-21 21:36:39 -0400 |
|---|---|---|
| committer | GitHub <noreply@github.com> | 2021-09-21 21:36:39 -0400 |
| commit | 4cb354469198344d17ce4ceaada22337bdd83cd8 (patch) | |
| tree | 1f77aff8343fbc0a2b1151c09d42c33f47885801 | |
| parent | b81647da4ed6189433123f26bb6e74c13b81de6d (diff) | |
| parent | 59ff034a066105826dc677ad27e617e8b56f2ef6 (diff) | |
| download | python-setuptools-git-4cb354469198344d17ce4ceaada22337bdd83cd8.tar.gz | |
Merge pull request #2792 from DiddiLeija/document-version-comparison
Document the version comparisons
| -rw-r--r-- | changelog.d/2792.doc.rst | 1 | ||||
| -rw-r--r-- | docs/userguide/distribution.rst | 11 |
2 files changed, 10 insertions, 2 deletions
diff --git a/changelog.d/2792.doc.rst b/changelog.d/2792.doc.rst new file mode 100644 index 00000000..3256d033 --- /dev/null +++ b/changelog.d/2792.doc.rst @@ -0,0 +1 @@ +Document how the legacy and non-legacy versions are compared, and reference to the `PEP 440 <https://www.python.org/dev/peps/pep-0440/>`_ scheme. diff --git a/docs/userguide/distribution.rst b/docs/userguide/distribution.rst index 377f7bb4..19bed1f9 100644 --- a/docs/userguide/distribution.rst +++ b/docs/userguide/distribution.rst @@ -161,7 +161,10 @@ without Cython. Specifying Your Project's Version --------------------------------- -Setuptools can work well with most versioning schemes; there are, however, a +Setuptools can work well with most versioning schemes. Over the years, +setuptools has tried to closely follow the +`PEP 440 <https://www.python.org/dev/peps/pep-0440/>`_ scheme, but it +also supports legacy versions. There are, however, a few special things to watch out for, in order to ensure that setuptools and other tools can always tell what version of your package is newer than another version. Knowing these things will also help you correctly specify what @@ -181,9 +184,13 @@ tag. Pre-release tags make a version be considered *older* than the version they are appended to. So, revision ``2.4`` is *newer* than revision ``2.4c1``, which in turn is newer than ``2.4b1`` or ``2.4a1``. Postrelease tags make a version be considered *newer* than the version they are appended to. So, -revisions like ``2.4-1`` and ``2.4pl3`` are newer than ``2.4``, but are *older* +revisions like ``2.4-1`` are newer than ``2.4``, but *older* than ``2.4.1`` (which has a higher release number). +In the case of legacy versions (for example, ``2.4pl1``), they are considered +older than non-legacy versions. Taking that in count, a revision ``2.4pl1`` +is *older* than ``2.4`` + A pre-release tag is a series of letters that are alphabetically before "final". Some examples of prerelease tags would include ``alpha``, ``beta``, ``a``, ``c``, ``dev``, and so on. You do not have to place a dot or dash |