diff options
Diffstat (limited to 'docs/developer-guide.rst')
| -rw-r--r-- | docs/developer-guide.rst | 149 |
1 files changed, 149 insertions, 0 deletions
diff --git a/docs/developer-guide.rst b/docs/developer-guide.rst new file mode 100644 index 00000000..e84cd640 --- /dev/null +++ b/docs/developer-guide.rst @@ -0,0 +1,149 @@ +================================ +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 <https://mail.python.org/mailman3/lists/distutils-sig.python.org/>`_, or on IRC (Freenode) at +#pypa. + +Discussions about development happen on the distutils-sig 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_resources/_vendor/vendored.txt`` and refreshed by way of +``paver update_vendored`` (pavement.py). |