From 6690c1ce74b9761608e6e5d395c93e25180721eb Mon Sep 17 00:00:00 2001 From: Anderson Bravalheri Date: Tue, 14 Jun 2022 18:46:59 +0100 Subject: [PATCH 1/5] Add warning about calling setup.py directly --- docs/userguide/distribution.rst | 13 +++++++++++++ 1 file changed, 13 insertions(+) diff --git a/docs/userguide/distribution.rst b/docs/userguide/distribution.rst index 543e629638..a3c4245edd 100644 --- a/docs/userguide/distribution.rst +++ b/docs/userguide/distribution.rst @@ -1,6 +1,19 @@ Tagging and "Daily Build" or "Snapshot" Releases ------------------------------------------------ +.. warning:: + Please note that running ``python setup.py ...`` directly is no longer + considered a good practice and that in the future the commands ``egg_info`` + and ``rotate`` will be deprecated. + + As a result, the instructions and information presented in this section + should be considered **transitional** while setuptools don't provide a + mechanism for tagging releases. + + Meanwhile, if you can also consider using :pypi:`setuptools-scm` to achieve + similar objectives. + + When a set of related projects are under development, it may be important to track finer-grained version increments than you would normally use for e.g. "stable" releases. While stable releases might be measured in dotted numbers From 4ea1593130eac82272049f536bb0b9debb5bdde9 Mon Sep 17 00:00:00 2001 From: Anderson Bravalheri Date: Tue, 14 Jun 2022 18:59:42 +0100 Subject: [PATCH 2/5] Reorganize sections regarding version --- docs/userguide/distribution.rst | 186 ++++++++++++++++---------------- 1 file changed, 92 insertions(+), 94 deletions(-) diff --git a/docs/userguide/distribution.rst b/docs/userguide/distribution.rst index a3c4245edd..baa278d533 100644 --- a/docs/userguide/distribution.rst +++ b/docs/userguide/distribution.rst @@ -1,3 +1,94 @@ +.. _Specifying Your Project's Version: + +Specifying Your Project's Version +================================= + +Setuptools can work well with most versioning schemes. Over the years, +setuptools has tried to closely follow the :pep`PEP 440` 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 +versions of other projects your project depends on. + +A version consists of an alternating series of release numbers and pre-release +or post-release tags. A release number is a series of digits punctuated by +dots, such as ``2.4`` or ``0.5``. Each series of digits is treated +numerically, so releases ``2.1`` and ``2.1.0`` are different ways to spell the +same release number, denoting the first subrelease of release 2. But ``2.10`` +is the *tenth* subrelease of release 2, and so is a different and newer release +from ``2.1`` or ``2.1.0``. Leading zeros within a series of digits are also +ignored, so ``2.01`` is the same as ``2.1``, and different from ``2.0.1``. + +Following a release number, you can have either a pre-release or post-release +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`` 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 +before the prerelease tag if it's immediately after a number, but it's okay to +do so if you prefer. Thus, ``2.4c1`` and ``2.4.c1`` and ``2.4-c1`` all +represent release candidate 1 of version ``2.4``, and are treated as identical +by setuptools. + +In addition, there are three special prerelease tags that are treated as if +they were the letter ``c``: ``pre``, ``preview``, and ``rc``. So, version +``2.4rc1``, ``2.4pre1`` and ``2.4preview1`` are all the exact same version as +``2.4c1``, and are treated as identical by setuptools. + +A post-release tag is either a series of letters that are alphabetically +greater than or equal to "final", or a dash (``-``). Post-release tags are +generally used to separate patch numbers, port numbers, build numbers, revision +numbers, or date stamps from the release number. For example, the version +``2.4-r1263`` might denote Subversion revision 1263 of a post-release patch of +version ``2.4``. Or you might use ``2.4-20051127`` to denote a date-stamped +post-release. + +Notice that after each pre or post-release tag, you are free to place another +release number, followed again by more pre- or post-release tags. For example, +``0.6a9.dev-r41475`` could denote Subversion revision 41475 of the in- +development version of the ninth alpha of release 0.6. Notice that ``dev`` is +a pre-release tag, so this version is a *lower* version number than ``0.6a9``, +which would be the actual ninth alpha of release 0.6. But the ``-r41475`` is +a post-release tag, so this version is *newer* than ``0.6a9.dev``. + +For the most part, setuptools' interpretation of version numbers is intuitive, +but here are a few tips that will keep you out of trouble in the corner cases: + +* Don't stick adjoining pre-release tags together without a dot or number + between them. Version ``1.9adev`` is the ``adev`` prerelease of ``1.9``, + *not* a development pre-release of ``1.9a``. Use ``.dev`` instead, as in + ``1.9a.dev``, or separate the prerelease tags with a number, as in + ``1.9a0dev``. ``1.9a.dev``, ``1.9a0dev``, and even ``1.9.a.dev`` are + identical versions from setuptools' point of view, so you can use whatever + scheme you prefer. + +* If you want to be certain that your chosen numbering scheme works the way + you think it will, you can use the ``pkg_resources.parse_version()`` function + to compare different version numbers:: + + >>> from pkg_resources import parse_version + >>> parse_version("1.9.a.dev") == parse_version("1.9a0dev") + True + >>> parse_version("2.1-rc2") < parse_version("2.1") + True + >>> parse_version("0.6a9dev-r41475") < parse_version("0.6a9") + True + +Once you've decided on a version numbering scheme for your project, you can +have setuptools automatically tag your in-development releases with various +pre- or post-release tags. See the following section for more details. + + Tagging and "Daily Build" or "Snapshot" Releases ------------------------------------------------ @@ -42,7 +133,7 @@ to generate a daily build or snapshot for. See the section below on the :ref:`Specifying Your Project's Version` for more information about how pre- and post-release tags affect how version numbers are interpreted. This is important in order to make sure that dependency processing tools will know -which versions of your project are newer than others.) +which versions of your project are newer than others). Finally, if you are creating builds frequently, and either building them in a downloadable location or are copying them to a distribution server, you should @@ -100,96 +191,3 @@ See the sections below on the :ref:`egg_info ` and :ref:`alias ` commands for more ideas. -.. _Specifying Your Project's Version: - -Specifying Your Project's Version ---------------------------------- - -Setuptools can work well with most versioning schemes. Over the years, -setuptools has tried to closely follow the -`PEP 440 `_ 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 -versions of other projects your project depends on. - -A version consists of an alternating series of release numbers and pre-release -or post-release tags. A release number is a series of digits punctuated by -dots, such as ``2.4`` or ``0.5``. Each series of digits is treated -numerically, so releases ``2.1`` and ``2.1.0`` are different ways to spell the -same release number, denoting the first subrelease of release 2. But ``2.10`` -is the *tenth* subrelease of release 2, and so is a different and newer release -from ``2.1`` or ``2.1.0``. Leading zeros within a series of digits are also -ignored, so ``2.01`` is the same as ``2.1``, and different from ``2.0.1``. - -Following a release number, you can have either a pre-release or post-release -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`` 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 -before the prerelease tag if it's immediately after a number, but it's okay to -do so if you prefer. Thus, ``2.4c1`` and ``2.4.c1`` and ``2.4-c1`` all -represent release candidate 1 of version ``2.4``, and are treated as identical -by setuptools. - -In addition, there are three special prerelease tags that are treated as if -they were the letter ``c``: ``pre``, ``preview``, and ``rc``. So, version -``2.4rc1``, ``2.4pre1`` and ``2.4preview1`` are all the exact same version as -``2.4c1``, and are treated as identical by setuptools. - -A post-release tag is either a series of letters that are alphabetically -greater than or equal to "final", or a dash (``-``). Post-release tags are -generally used to separate patch numbers, port numbers, build numbers, revision -numbers, or date stamps from the release number. For example, the version -``2.4-r1263`` might denote Subversion revision 1263 of a post-release patch of -version ``2.4``. Or you might use ``2.4-20051127`` to denote a date-stamped -post-release. - -Notice that after each pre or post-release tag, you are free to place another -release number, followed again by more pre- or post-release tags. For example, -``0.6a9.dev-r41475`` could denote Subversion revision 41475 of the in- -development version of the ninth alpha of release 0.6. Notice that ``dev`` is -a pre-release tag, so this version is a *lower* version number than ``0.6a9``, -which would be the actual ninth alpha of release 0.6. But the ``-r41475`` is -a post-release tag, so this version is *newer* than ``0.6a9.dev``. - -For the most part, setuptools' interpretation of version numbers is intuitive, -but here are a few tips that will keep you out of trouble in the corner cases: - -* Don't stick adjoining pre-release tags together without a dot or number - between them. Version ``1.9adev`` is the ``adev`` prerelease of ``1.9``, - *not* a development pre-release of ``1.9a``. Use ``.dev`` instead, as in - ``1.9a.dev``, or separate the prerelease tags with a number, as in - ``1.9a0dev``. ``1.9a.dev``, ``1.9a0dev``, and even ``1.9.a.dev`` are - identical versions from setuptools' point of view, so you can use whatever - scheme you prefer. - -* If you want to be certain that your chosen numbering scheme works the way - you think it will, you can use the ``pkg_resources.parse_version()`` function - to compare different version numbers:: - - >>> from pkg_resources import parse_version - >>> parse_version("1.9.a.dev") == parse_version("1.9a0dev") - True - >>> parse_version("2.1-rc2") < parse_version("2.1") - True - >>> parse_version("0.6a9dev-r41475") < parse_version("0.6a9") - True - -Once you've decided on a version numbering scheme for your project, you can -have setuptools automatically tag your in-development releases with various -pre- or post-release tags. See the following sections for more details: - -* `Tagging and "Daily Build" or "Snapshot" Releases`_ -* The :ref:`egg_info ` command From 26335254b1f1388f73a1a92613f2d0619ef04043 Mon Sep 17 00:00:00 2001 From: Anderson Bravalheri Date: Tue, 14 Jun 2022 21:45:30 +0100 Subject: [PATCH 3/5] Small fixes in the rst --- docs/userguide/distribution.rst | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/docs/userguide/distribution.rst b/docs/userguide/distribution.rst index baa278d533..3f33f9bfc5 100644 --- a/docs/userguide/distribution.rst +++ b/docs/userguide/distribution.rst @@ -4,7 +4,7 @@ Specifying Your Project's Version ================================= Setuptools can work well with most versioning schemes. Over the years, -setuptools has tried to closely follow the :pep`PEP 440` scheme, but it +setuptools has tried to closely follow the :pep:`440` 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 @@ -189,5 +189,3 @@ You can then use it like this:: Or of course you can create more elaborate aliases that do all of the above. See the sections below on the :ref:`egg_info ` and :ref:`alias ` commands for more ideas. - - From f081ba1c79197ddd019658c43132a4f5962ff58f Mon Sep 17 00:00:00 2001 From: Anderson Bravalheri Date: Tue, 14 Jun 2022 21:47:25 +0100 Subject: [PATCH 4/5] Promote title level --- docs/userguide/distribution.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/userguide/distribution.rst b/docs/userguide/distribution.rst index 3f33f9bfc5..be95a88106 100644 --- a/docs/userguide/distribution.rst +++ b/docs/userguide/distribution.rst @@ -158,7 +158,7 @@ of the ``daily`` alias, so that projects that didn't define their own would use the appropriate defaults.) Making "Official" (Non-Snapshot) Releases -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +----------------------------------------- When you make an official release, creating source or binary distributions, you will need to override the tag settings from ``setup.cfg``, so that you From 0b6c28f9c45ed45204535172b19f3f2345d92330 Mon Sep 17 00:00:00 2001 From: Anderson Bravalheri Date: Tue, 14 Jun 2022 22:27:50 +0100 Subject: [PATCH 5/5] Add news fragment --- changelog.d/3374.doc.rst | 5 +++++ 1 file changed, 5 insertions(+) create mode 100644 changelog.d/3374.doc.rst diff --git a/changelog.d/3374.doc.rst b/changelog.d/3374.doc.rst new file mode 100644 index 0000000000..c00797ba2d --- /dev/null +++ b/changelog.d/3374.doc.rst @@ -0,0 +1,5 @@ +Added clarification that using ``python setup.py egg_info`` commands to +manage project versions is only supported in a *transitional* basis, and +that eventually ``egg_info`` will be deprecated. + +Reorganized sections with tips for managing versions.