150 lines
5.4 KiB
Plaintext
150 lines
5.4 KiB
Plaintext
================================
|
|
Developer's Guide for Setuptools
|
|
================================
|
|
|
|
If you want to know more about contributing on Setuptools, this is the place.
|
|
|
|
|
|
.. contents:: **Table of Contents**
|
|
|
|
|
|
-------------------
|
|
Recommended Reading
|
|
-------------------
|
|
|
|
Please read `How to write the perfect pull request
|
|
<https://blog.jaraco.com/how-to-write-perfect-pull-request/>`_ for some tips
|
|
on contributing to open source projects. Although the article is not
|
|
authoritative, it was authored by the maintainer of Setuptools, so reflects
|
|
his opinions and will improve the likelihood of acceptance and quality of
|
|
contribution.
|
|
|
|
------------------
|
|
Project Management
|
|
------------------
|
|
|
|
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 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
|
|
#pypa.
|
|
|
|
Discussions about development happen on the pypa-dev mailing list or on
|
|
`Gitter <https://gitter.im/pypa/setuptools>`_.
|
|
|
|
-----------------
|
|
Authoring Tickets
|
|
-----------------
|
|
|
|
Before authoring any source code, it's often prudent to file a ticket
|
|
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 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
|
|
clarification. The ticket provides a record of the purpose for the change and
|
|
any hard decisions that were made. It provides a single place for others to
|
|
reference when trying to understand why the software operates the way it does
|
|
or why certain changes were made.
|
|
|
|
Setuptools makes extensive use of hyperlinks to tickets in the changelog so
|
|
that system integrators and other users can get a quick summary, but then
|
|
jump to the in-depth discussion about any subject referenced.
|
|
|
|
---------------------
|
|
Making a pull request
|
|
---------------------
|
|
|
|
When making a pull request, please include a short summary of the changes
|
|
and a reference to any issue tickets that the PR is intended to solve.
|
|
All PRs with code changes should include tests. All changes should include a
|
|
changelog entry.
|
|
|
|
``setuptools`` uses `towncrier <https://pypi.org/project/towncrier/>`_
|
|
for changelog management, so when making a PR, please add a news fragment in the
|
|
``changelog.d/`` folder. Changelog files are written in reStructuredText and
|
|
should be a 1 or 2 sentence description of the substantive changes in the PR.
|
|
They should be named ``<pr_number>.<category>.rst``, where the categories are:
|
|
|
|
- ``change``: Any backwards compatible code change
|
|
- ``breaking``: Any backwards-compatibility breaking change
|
|
- ``doc``: A change to the documentation
|
|
- ``misc``: Changes internal to the repo like CI, test and build changes
|
|
- ``deprecation``: For deprecations of an existing feature or behavior
|
|
|
|
A pull request may have more than one of these components, for example a code
|
|
change may introduce a new feature that deprecates an old feature, in which
|
|
case two fragments should be added. It is not necessary to make a separate
|
|
documentation fragment for documentation changes accompanying the relevant
|
|
code changes. See the following for an example news fragment:
|
|
|
|
.. code-block:: bash
|
|
|
|
$ cat changelog.d/1288.change.rst
|
|
Add support for maintainer in PKG-INFO
|
|
|
|
-------------------
|
|
Auto-Merge Requests
|
|
-------------------
|
|
|
|
To support running all code through CI, even lightweight contributions,
|
|
the project employs Mergify to auto-merge pull requests tagged as
|
|
auto-merge.
|
|
|
|
Use ``hub pull-request -l auto-merge`` to create such a pull request
|
|
from the command line after pushing a new branch.
|
|
|
|
-------
|
|
Testing
|
|
-------
|
|
|
|
The primary tests are run using tox. Make sure you have tox installed,
|
|
and invoke it::
|
|
|
|
$ tox
|
|
|
|
Under continuous integration, additional tests may be run. See the
|
|
``.travis.yml`` file for full details on the tests run under Travis-CI.
|
|
|
|
-------------------
|
|
Semantic Versioning
|
|
-------------------
|
|
|
|
Setuptools follows ``semver``.
|
|
|
|
.. explain value of reflecting meaning in versions.
|
|
|
|
----------------------
|
|
Building Documentation
|
|
----------------------
|
|
|
|
Setuptools relies on the `Sphinx`_ system for building documentation.
|
|
The `published documentation`_ is hosted on Read the Docs.
|
|
|
|
To build the docs locally, use tox::
|
|
|
|
$ tox -e docs
|
|
|
|
.. _Sphinx: http://www.sphinx-doc.org/en/master/
|
|
.. _published documentation: https://setuptools.readthedocs.io/en/latest/
|
|
|
|
---------------------
|
|
Vendored Dependencies
|
|
---------------------
|
|
|
|
Setuptools has some dependencies, but due to `bootstrapping issues
|
|
<https://github.com/pypa/setuptools/issues/980>`, those dependencies
|
|
cannot be declared as they won't be resolved soon enough to build
|
|
setuptools from source. Eventually, this limitation may be lifted as
|
|
PEP 517/518 reach ubiquitous adoption, but for now, Setuptools
|
|
cannot declare dependencies other than through
|
|
``setuptools/_vendor/vendored.txt`` and
|
|
``pkg_reosurces/_vendor/vendored.txt`` and refreshed by way of
|
|
``paver update_vendored`` (pavement.py).
|