[Docs] Improve instructions for dealing with version

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.

docs/userguide/distribution.rst

@@ -1,100 +1,10 @@
-Tagging and "Daily Build" or "Snapshot" Releases
-------------------------------------------------
-
-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
-with alpha/beta/etc. status codes, development versions of a project often
-need to be tracked by revision or build number or even build date.  This is
-especially true when projects in development need to refer to one another, and
-therefore may literally need an up-to-the-minute version of something!
-
-To support these scenarios, ``setuptools`` allows you to "tag" your source and
-egg distributions by adding one or more of the following to the project's
-"official" version identifier:
-
-* A manually-specified pre-release tag, such as "build" or "dev", or a
-  manually-specified post-release tag, such as a build or revision number
-  (``--tag-build=STRING, -bSTRING``)
-
-* An 8-character representation of the build date (``--tag-date, -d``), as
-  a postrelease tag
-
-You can add these tags by adding ``egg_info`` and the desired options to
-the command line ahead of the ``sdist`` or ``bdist`` commands that you want
-to generate a daily build or snapshot for.  See the section below on the
-:ref:`egg_info <egg_info>` command for more details.
-
-(Also, before you release your project, be sure to see the section on
-: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.)
-
-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
-probably also check out the :ref:`rotate <rotate>` command, which lets you automatically
-delete all but the N most-recently-modified distributions matching a glob
-pattern.  So, you can use a command line like::
-
-    setup.py egg_info -rbDEV bdist_egg rotate -m.egg -k3
-
-to build an egg whose version info includes "DEV-rNNNN" (where NNNN is the
-most recent Subversion revision that affected the source tree), and then
-delete any egg files from the distribution directory except for the three
-that were built most recently.
-
-If you have to manage automated builds for multiple packages, each with
-different tagging and rotation policies, you may also want to check out the
-:ref:`alias <alias>` command, which would let each package define an alias like ``daily``
-that would perform the necessary tag, build, and rotate commands.  Then, a
-simpler script or cron job could just run ``setup.py daily`` in each project
-directory.  (And, you could also define sitewide or per-user default versions
-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
-don't end up registering versions like ``foobar-0.7a1.dev-r34832``.  This is
-easy to do if you are developing on the trunk and using tags or branches for
-your releases - just make the change to ``setup.cfg`` after branching or
-tagging the release, so the trunk will still produce development snapshots.
-
-Alternately, if you are not branching for releases, you can override the
-default version options on the command line, using something like::
-
-    setup.py egg_info -Db "" sdist bdist_egg
-
-The first part of this command (``egg_info -Db ""``) will override the
-configured tag information, before creating source and binary eggs. Thus, these
-commands will use the plain version from your ``setup.py``, without adding the
-build designation string.
-
-Of course, if you will be doing this a lot, you may wish to create a personal
-alias for this operation, e.g.::
-
-    setup.py alias -u release egg_info -Db ""
-
-You can then use it like this::
-
-    setup.py release sdist bdist_egg
-
-Or of course you can create more elaborate aliases that do all of the above.
-See the sections below on the :ref:`egg_info <egg_info>` and
-:ref:`alias <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 <https://www.python.org/dev/peps/pep-0440/>`_ 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
@@ -176,7 +86,106 @@ but here are a few tips that will keep you out of trouble in the corner cases:
 
 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:
+pre- or post-release tags. See the following section for more details.
 
-* `Tagging and "Daily Build" or "Snapshot" Releases`_
-* The :ref:`egg_info <egg_info>` command
+
+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
+with alpha/beta/etc. status codes, development versions of a project often
+need to be tracked by revision or build number or even build date.  This is
+especially true when projects in development need to refer to one another, and
+therefore may literally need an up-to-the-minute version of something!
+
+To support these scenarios, ``setuptools`` allows you to "tag" your source and
+egg distributions by adding one or more of the following to the project's
+"official" version identifier:
+
+* A manually-specified pre-release tag, such as "build" or "dev", or a
+  manually-specified post-release tag, such as a build or revision number
+  (``--tag-build=STRING, -bSTRING``)
+
+* An 8-character representation of the build date (``--tag-date, -d``), as
+  a postrelease tag
+
+You can add these tags by adding ``egg_info`` and the desired options to
+the command line ahead of the ``sdist`` or ``bdist`` commands that you want
+to generate a daily build or snapshot for.  See the section below on the
+:ref:`egg_info <egg_info>` command for more details.
+
+(Also, before you release your project, be sure to see the section on
+: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).
+
+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
+probably also check out the :ref:`rotate <rotate>` command, which lets you automatically
+delete all but the N most-recently-modified distributions matching a glob
+pattern.  So, you can use a command line like::
+
+    setup.py egg_info -rbDEV bdist_egg rotate -m.egg -k3
+
+to build an egg whose version info includes "DEV-rNNNN" (where NNNN is the
+most recent Subversion revision that affected the source tree), and then
+delete any egg files from the distribution directory except for the three
+that were built most recently.
+
+If you have to manage automated builds for multiple packages, each with
+different tagging and rotation policies, you may also want to check out the
+:ref:`alias <alias>` command, which would let each package define an alias like ``daily``
+that would perform the necessary tag, build, and rotate commands.  Then, a
+simpler script or cron job could just run ``setup.py daily`` in each project
+directory.  (And, you could also define sitewide or per-user default versions
+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
+don't end up registering versions like ``foobar-0.7a1.dev-r34832``.  This is
+easy to do if you are developing on the trunk and using tags or branches for
+your releases - just make the change to ``setup.cfg`` after branching or
+tagging the release, so the trunk will still produce development snapshots.
+
+Alternately, if you are not branching for releases, you can override the
+default version options on the command line, using something like::
+
+    setup.py egg_info -Db "" sdist bdist_egg
+
+The first part of this command (``egg_info -Db ""``) will override the
+configured tag information, before creating source and binary eggs. Thus, these
+commands will use the plain version from your ``setup.py``, without adding the
+build designation string.
+
+Of course, if you will be doing this a lot, you may wish to create a personal
+alias for this operation, e.g.::
+
+    setup.py alias -u release egg_info -Db ""
+
+You can then use it like this::
+
+    setup.py release sdist bdist_egg
+
+Or of course you can create more elaborate aliases that do all of the above.
+See the sections below on the :ref:`egg_info <egg_info>` and
+:ref:`alias <alias>` commands for more ideas.