Merge with master

6 files changed, 111 insertions, 156 deletions

diff --git a/docs/conf.py b/docs/conf.py
index 846e4b3e..8bba3e94 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -196,7 +196,7 @@ latex_documents = [
 #latex_use_modindex = True
 
 link_files = {
-	'CHANGES.txt': dict(
+	'CHANGES.rst': dict(
 		using=dict(
 			BB='https://bitbucket.org',
 			GH='https://github.com',
@@ -204,11 +204,11 @@ link_files = {
 		replace=[
 			dict(
 				pattern=r"(Issue )?#(?P<issue>\d+)",
-				url='{BB}/pypa/setuptools/issue/{issue}',
+				url='{GH}/pypa/setuptools/issues/{issue}',
 			),
 			dict(
-				pattern=r"Pull Request ?#(?P<pull_request>\d+)",
-				url='{BB}/pypa/setuptools/pull-request/{pull_request}',
+				pattern=r"BB Pull Request ?#(?P<bb_pull_request>\d+)",
+				url='{BB}/pypa/setuptools/pull-request/{bb_pull_request}',
 			),
 			dict(
 				pattern=r"Distribute #(?P<distribute>\d+)",
@@ -246,6 +246,14 @@ link_files = {
 				pattern=r"[Pp]ackaging (?P<packaging_ver>\d+(\.\d+)+)",
 				url='{GH}/pypa/packaging/blob/{packaging_ver}/CHANGELOG.rst',
 			),
+			dict(
+				pattern=r"PEP[- ](?P<pep_number>\d+)",
+				url='https://www.python.org/dev/peps/pep-{pep_number:0>4}/',
+			),
+			dict(
+				pattern=r"^(?m)((?P<scm_version>v?\d+(\.\d+){1,2}))\n[-=]+\n",
+				with_scm="{text}\n{rev[timestamp]:%d %b %Y}\n",
+			),
 		],
 	),
 }
diff --git a/docs/developer-guide.txt b/docs/developer-guide.txt
index ae33649b..7cd3c6d2 100644
--- a/docs/developer-guide.txt
+++ b/docs/developer-guide.txt
@@ -23,10 +23,10 @@ quality of contribution.
 Project Management
 ------------------
 
-Setuptools is maintained primarily in Bitbucket at `this home
-<https://bitbucket.org/pypa/setuptools>`_. Setuptools is maintained under the
+Setuptools is maintained primarily in Github at `this home
+<https://github.com/pypa/setuptools>`_. Setuptools is maintained under the
 Python Packaging Authority (PyPA) with several core contributors. All bugs
-for Setuptools are filed and the canonical source is maintained in Bitbucket.
+for Setuptools are filed and the canonical source is maintained in Github.
 
 User support and discussions are done through the issue tracker (for specific)
 issues, through the distutils-sig mailing list, or on IRC (Freenode) at
@@ -44,7 +44,7 @@ describing the motivation behind making changes. First search to see if a
 ticket already exists for your issue. If not, create one. Try to think from
 the perspective of the reader. Explain what behavior you expected, what you
 got instead, and what factors might have contributed to the unexpected
-behavior. In Bitbucket, surround a block of code or traceback with the triple
+behavior. In Github, surround a block of code or traceback with the triple
 backtick "\`\`\`" so that it is formatted nicely.
 
 Filing a ticket provides a forum for justification, discussion, and
@@ -61,17 +61,17 @@ jump to the in-depth discussion about any subject referenced.
 Source Code
 -----------
 
-Grab the code at Bitbucket::
+Grab the code at Github::
 
-    $ hg clone https://bitbucket.org/pypa/setuptools
+    $ git checkout https://github.com/pypa/setuptools
 
 If you want to contribute changes, we recommend you fork the repository on
-Bitbucket, commit the changes to your repository, and then make a pull request
-on Bitbucket. If you make some changes, don't forget to:
+Github, commit the changes to your repository, and then make a pull request
+on Github. If you make some changes, don't forget to:
 
-- add a note in CHANGES.txt
+- add a note in CHANGES.rst
 
-Please commit all changes in the 'default' branch against the latest available
+Please commit all changes in the 'master' branch against the latest available
 commit or for bug-fixes, against an earlier commit or release in which the
 bug occurred.
 
@@ -79,12 +79,11 @@ If you find yourself working on more than one issue at a time, Setuptools
 generally prefers Git-style branches, so use Mercurial bookmarks or Git
 branches or multiple forks to maintain separate efforts.
 
-Setuptools also maintains an unofficial `Git mirror in Github
-<https://github.com/jaraco/setuptools>`_. Contributors are welcome to submit
-pull requests here, but because they are not integrated with the Bitbucket
-Issue tracker, linking pull requests to tickets is more difficult. The
-Continuous Integration tests that validate every release are run from this
-mirror.
+The Continuous Integration tests that validate every release are run
+from this repository.
+
+For posterity, the old `Bitbucket mirror
+<https://bitbucket.org/pypa/setuptools>`_ is available.
 
 -------
 Testing
@@ -104,10 +103,7 @@ Under continuous integration, additional tests may be run. See the
 Semantic Versioning
 -------------------
 
-Setuptools follows ``semver`` with some exceptions:
-
-- Uses two-segment version when three segment version ends in zero
-- Omits 'v' prefix for tags.
+Setuptools follows ``semver``.
 
 .. explain value of reflecting meaning in versions.
 
diff --git a/docs/history.txt b/docs/history.txt
index 268137cd..8e217503 100644
--- a/docs/history.txt
+++ b/docs/history.txt
@@ -5,4 +5,4 @@
 History
 *******
 
-.. include:: ../CHANGES (links).txt
+.. include:: ../CHANGES (links).rst
diff --git a/docs/pkg_resources.txt b/docs/pkg_resources.txt
index 3d40a1a2..7b979ec3 100644
--- a/docs/pkg_resources.txt
+++ b/docs/pkg_resources.txt
@@ -590,20 +590,7 @@ Requirements Parsing
     parse multiple specifiers from a string or iterable of strings, use
     ``parse_requirements()`` instead.)
 
-    The syntax of a requirement specifier can be defined in EBNF as follows::
-
-        requirement  ::= project_name extras? versionspec?
-        versionspec  ::= comparison version (',' comparison version)*
-        comparison   ::= '<' | '<=' | '!=' | '==' | '>=' | '>' | '~=' | '==='
-        extras       ::= '[' extralist? ']'
-        extralist    ::= identifier (',' identifier)*
-        project_name ::= identifier
-        identifier   ::= [-A-Za-z0-9_]+
-        version      ::= [-A-Za-z0-9_.]+
-
-    Tokens can be separated by whitespace, and a requirement can be continued
-    over multiple lines using a backslash (``\\``).  Line-end comments (using
-    ``#``) are also allowed.
+    The syntax of a requirement specifier is defined in full in PEP 508.
 
     Some examples of valid requirement specifiers::
 
@@ -611,6 +598,7 @@ Requirements Parsing
         Fizzy [foo, bar]
         PickyThing<1.6,>1.9,!=1.9.6,<2.0a0,==2.4c1
         SomethingWhoseVersionIDontCareAbout
+        SomethingWithMarker[foo]>1.0;python_version<"2.7"
 
     The project name is the only required portion of a requirement string, and
     if it's the only thing supplied, the requirement will accept any version
@@ -631,6 +619,11 @@ Requirements Parsing
     ``pkg_resources.require('Report-O-Rama[PDF]')`` to add the necessary
     distributions to sys.path at runtime.
 
+    The "markers" in a requirement are used to specify when a requirement
+    should be installed -- the requirement will be installed if the marker
+    evaluates as true in the current environment. For example, specifying
+    ``argparse;python_version<"2.7"`` will not install in an Python 2.7 or 3.3
+    environment, but will in a Python 2.6 environment.
 
 ``Requirement`` Methods and Attributes
 --------------------------------------
@@ -680,6 +673,12 @@ Requirements Parsing
     order.  The `op` in each tuple is a comparison operator, represented as
     a string.  The `version` is the (unparsed) version number.
 
+``marker``
+    An instance of ``packaging.markers.Marker`` that allows evaluation
+    against the current environment. May be None if no marker specified.
+
+``url``
+    The location to download the requirement from if specified.
 
 Entry Points
 ============
diff --git a/docs/releases.txt b/docs/releases.txt
index a9742c20..3f29334a 100644
--- a/docs/releases.txt
+++ b/docs/releases.txt
@@ -3,19 +3,14 @@ Release Process
 ===============
 
 In order to allow for rapid, predictable releases, Setuptools uses a
-mechanical technique for releases. The release script, ``release.py`` in the
-repository, defines the details of the releases, and is executed by the
-`jaraco.packaging <https://bitbucket.org/jaraco/jaraco.packaging>`_ release
-module. The script does some checks (some interactive) and fully automates
-the release process.
+mechanical technique for releases, enacted by Travis following a
+successful build of a tagged release per
+`PyPI deployment <https://docs.travis-ci.com/user/deployment/pypi>`_.
 
-A Setuptools release manager must have maintainer access on PyPI to the
-project and administrative access to the Bitbucket project.
-
-To make a release, run the following from a Mercurial checkout at the
-revision slated for release::
-
-    python -m jaraco.packaging.release
+To cut a release, install and run ``bumpversion {part}`` where ``part``
+is major, minor, or patch based on the scope of the changes in the
+release. Then, push the commits to the master branch. If tests pass,
+the release will be uploaded to PyPI.
 
 Bootstrap Bookmark
 ------------------
@@ -23,7 +18,7 @@ Bootstrap Bookmark
 Setuptools has a bootstrap script (ez_setup.py) which is hosted in the
 repository and must be updated with each release (to bump the default version).
 The "published" version of the script is the one indicated by the ``bootstrap``
-bookmark (Mercurial) or branch (Git).
+branch.
 
 Therefore, the latest bootstrap script can be retrieved by checking out the
 repository at that bookmark. It's also possible to get the bootstrap script for
@@ -57,7 +52,5 @@ corrected quickly, in many cases before other users have yet to encounter them.
 Release Managers
 ----------------
 
-Jason R. Coombs is the primary release manager. Additionally, the following
-people have access to create releases:
-
-- Matthew Iversen (Ivoz)
+Additionally, anyone with push access to the master branch has access to cut
+releases.
diff --git a/docs/setuptools.txt b/docs/setuptools.txt
index d6a62de8..eeeab937 100644
--- a/docs/setuptools.txt
+++ b/docs/setuptools.txt
@@ -258,10 +258,9 @@ unless you need the associated ``setuptools`` feature.
 
 ``include_package_data``
     If set to ``True``, this tells ``setuptools`` to automatically include any
-    data files it finds inside your package directories, that are either under
-    CVS or Subversion control, or which are specified by your ``MANIFEST.in``
-    file.  For more information, see the section below on `Including Data
-    Files`_.
+    data files it finds inside your package directories that are specified by
+    your ``MANIFEST.in`` file.  For more information, see the section below on
+    `Including Data Files`_.
 
 ``exclude_package_data``
     A dictionary mapping package names to lists of glob patterns that should
@@ -785,17 +784,15 @@ e.g.::
     )
 
 This tells setuptools to install any data files it finds in your packages.
-The data files must be under CVS or Subversion control, or else they must be
-specified via the distutils' ``MANIFEST.in`` file.  (They can also be tracked
-by another revision control system, using an appropriate plugin.  See the
-section below on `Adding Support for Other Revision Control Systems`_ for
-information on how to write such plugins.)
-
-If the data files are not under version control, or are not in a supported
-version control system, or if you want finer-grained control over what files
-are included (for example, if you have documentation files in your package
-directories and want to exclude them from installation), then you can also use
-the ``package_data`` keyword, e.g.::
+The data files must be specified via the distutils' ``MANIFEST.in`` file.
+(They can also be tracked by a revision control system, using an appropriate
+plugin.  See the section below on `Adding Support for Revision Control
+Systems`_ for information on how to write such plugins.)
+
+If you want finer-grained control over what files are included (for example,
+if you have documentation files in your package directories and want to exclude
+them from installation), then you can also use the ``package_data`` keyword,
+e.g.::
 
     from setuptools import setup, find_packages
     setup(
@@ -853,8 +850,7 @@ converts slashes to appropriate platform-specific separators at build time.
 Python 2.4; there is `some documentation for the feature`__ available on the
 python.org website.  If using the setuptools-specific ``include_package_data``
 argument, files specified by ``package_data`` will *not* be automatically
-added to the manifest unless they are tracked by a supported version control
-system, or are listed in the MANIFEST.in file.)
+added to the manifest unless they are listed in the MANIFEST.in file.)
 
 __ http://docs.python.org/dist/node11.html
 
@@ -887,8 +883,7 @@ included as a result of using ``include_package_data``.
 In summary, the three options allow you to:
 
 ``include_package_data``
-    Accept all data files and directories matched by ``MANIFEST.in`` or found
-    in source control.
+    Accept all data files and directories matched by ``MANIFEST.in``.
 
 ``package_data``
     Specify additional patterns to match files and directories that may or may
@@ -1231,15 +1226,14 @@ Your Project's Dependencies
     target audience isn't able to compile packages (e.g. most Windows users)
     and your package or some of its dependencies include C code.
 
-Subversion or CVS Users and Co-Developers
+Revision Control System Users and Co-Developers
     Users and co-developers who are tracking your in-development code using
-    CVS, Subversion, or some other revision control system should probably read
-    this manual's sections regarding such development.  Alternately, you may
-    wish to create a quick-reference guide containing the tips from this manual
-    that apply to your particular situation.  For example, if you recommend
-    that people use ``setup.py develop`` when tracking your in-development
-    code, you should let them know that this needs to be run after every update
-    or commit.
+    a revision control system should probably read this manual's sections
+    regarding such development.  Alternately, you may wish to create a
+    quick-reference guide containing the tips from this manual that apply to
+    your particular situation.  For example, if you recommend that people use
+    ``setup.py develop`` when tracking your in-development code, you should let
+    them know that this needs to be run after every update or commit.
 
     Similarly, if you remove modules or data files from your project, you
     should remind them to run ``setup.py clean --all`` and delete any obsolete
@@ -1468,18 +1462,11 @@ Generating Source Distributions
 -------------------------------
 
 ``setuptools`` enhances the distutils' default algorithm for source file
-selection, so that all files managed by CVS or Subversion in your project tree
-are included in any source distribution you build.  This is a big improvement
-over having to manually write a ``MANIFEST.in`` file and try to keep it in
-sync with your project.  So, if you are using CVS or Subversion, and your
-source distributions only need to include files that you're tracking in
-revision control, don't create a ``MANIFEST.in`` file for your project.
-(And, if you already have one, you might consider deleting it the next time
-you would otherwise have to change it.)
-
-(NOTE: other revision control systems besides CVS and Subversion can be
-supported using plugins; see the section below on `Adding Support for Other
-Revision Control Systems`_ for information on how to write such plugins.)
+selection with pluggable endpoints for looking up files to include. If you are
+using a revision control system, and your source distributions only need to
+include files that you're tracking in revision control, use a corresponding
+plugin instead of writing a ``MANIFEST.in`` file. See the section below on
+`Adding Support for Revision Control Systems`_ for information on plugins.
 
 If you need to include automatically generated files, or files that are kept in
 an unsupported revision control system, you'll need to create a ``MANIFEST.in``
@@ -1501,12 +1488,6 @@ the options that the distutils' more complex ``sdist`` process requires.  For
 all practical purposes, you'll probably use only the ``--formats`` option, if
 you use any option at all.
 
-(By the way, if you're using some other revision control system, you might
-consider creating and publishing a `revision control plugin for setuptools`_.)
-
-
-.. _revision control plugin for setuptools: `Adding Support for Other Revision Control Systems`_
-
 
 Making your package available for EasyInstall
 ---------------------------------------------
@@ -1687,9 +1668,10 @@ Of course, for this to work, your source distributions must include the C
 code generated by Pyrex, as well as your original ``.pyx`` files.  This means
 that you will probably want to include current ``.c`` files in your revision
 control system, rebuilding them whenever you check changes in for the ``.pyx``
-source files.  This will ensure that people tracking your project in CVS or
-Subversion will be able to build it even if they don't have Pyrex installed,
-and that your source releases will be similarly usable with or without Pyrex.
+source files.  This will ensure that people tracking your project in a revision
+control system will be able to build it even if they don't have Pyrex
+installed, and that your source releases will be similarly usable with or
+without Pyrex.
 
 
 -----------------
@@ -2328,54 +2310,25 @@ available:
 ``upload`` - Upload source and/or egg distributions to PyPI
 ===========================================================
 
-PyPI now supports uploading project files for redistribution; uploaded files
-are easily found by EasyInstall, even if you don't have download links on your
-project's home page.
-
-Although Python 2.5 will support uploading all types of distributions to PyPI,
-setuptools only supports source distributions and eggs.  (This is partly
-because PyPI's upload support is currently broken for various other file
-types.)  To upload files, you must include the ``upload`` command *after* the
-``sdist`` or ``bdist_egg`` commands on the setup command line.  For example::
+The ``upload`` command is implemented and `documented
+<https://docs.python.org/3.1/distutils/uploading.html>`_
+in distutils.
 
-    setup.py bdist_egg upload         # create an egg and upload it
-    setup.py sdist upload             # create a source distro and upload it
-    setup.py sdist bdist_egg upload   # create and upload both
+Setuptools augments the ``upload`` command with support
+for `keyring <https://pypi.python.org/pypi/keyring>`_,
+allowing the password to be stored in a secure
+location and not in plaintext in the .pypirc file. To use
+keyring, first install keyring and set the password for
+the relevant repository, e.g.::
 
-Note that to upload files for a project, the corresponding version must already
-be registered with PyPI, using the distutils ``register`` command.  It's
-usually a good idea to include the ``register`` command at the start of the
-command line, so that any registration problems can be found and fixed before
-building and uploading the distributions, e.g.::
+    python -m keyring set <repository> <username>
+    Password for '<username>' in '<repository>': ********
 
-    setup.py register sdist bdist_egg upload
+Then, in .pypirc, set the repository configuration as normal,
+but omit the password. Thereafter, uploads will use the
+password from the keyring.
 
-This will update PyPI's listing for your project's current version.
-
-Note, by the way, that the metadata in your ``setup()`` call determines what
-will be listed in PyPI for your package.  Try to fill out as much of it as
-possible, as it will save you a lot of trouble manually adding and updating
-your PyPI listings.  Just put it in ``setup.py`` and use the ``register``
-command to keep PyPI up to date.
-
-The ``upload`` command has a few options worth noting:
-
-``--sign, -s``
-    Sign each uploaded file using GPG (GNU Privacy Guard).  The ``gpg`` program
-    must be available for execution on the system ``PATH``.
-
-``--identity=NAME, -i NAME``
-    Specify the identity or key name for GPG to use when signing.  The value of
-    this option will be passed through the ``--local-user`` option of the
-    ``gpg`` program.
-
-``--show-response``
-    Display the full response text from server; this is useful for debugging
-    PyPI problems.
-
-``--repository=URL, -r URL``
-    The URL of the repository to upload to.  Defaults to
-    https://pypi.python.org/pypi (i.e., the main PyPI installation).
+New in 20.1: Added keyring support.
 
 .. _upload_docs:
 
@@ -2598,15 +2551,21 @@ the ``cmd`` object's ``write_file()``, ``delete_file()``, and
 those methods' docstrings for more details.
 
 
-Adding Support for Other Revision Control Systems
+Adding Support for Revision Control Systems
 -------------------------------------------------
 
-If you would like to create a plugin for ``setuptools`` to find files in
-source control systems, you can do so by adding an
-entry point to the ``setuptools.file_finders`` group.  The entry point should
-be a function accepting a single directory name, and should yield
-all the filenames within that directory (and any subdirectories thereof) that
-are under revision control.
+If the files you want to include in the source distribution are tracked using
+Git, Mercurial or SVN, you can use the following packages to achieve that:
+
+- Git and Mercurial: `setuptools_scm <https://pypi.python.org/pypi/setuptools_scm>`_
+- SVN: `setuptools_svn <https://pypi.python.org/pypi/setuptools_svn>`_
+
+If you would like to create a plugin for ``setuptools`` to find files tracked
+by another revision control system, you can do so by adding an entry point to
+the ``setuptools.file_finders`` group.  The entry point should be a function
+accepting a single directory name, and should yield all the filenames within
+that directory (and any subdirectories thereof) that are under revision
+control.
 
 For example, if you were going to create a plugin for a revision control system
 called "foobar", you would write a function something like this:
@@ -2699,5 +2658,5 @@ confirmed via the list are actual bugs, and which you have reduced to a minimal
 set of steps to reproduce.
 
 .. _distutils-sig mailing list: http://mail.python.org/pipermail/distutils-sig/
-.. _setuptools bug tracker: https://bitbucket.org/pypa/setuptools/
+.. _setuptools bug tracker: https://github.com/pypa/setuptools/