1================================
2Developer's Guide for Setuptools
3================================
4
5If you want to know more about contributing on Setuptools, this is the place.
6
7
8-------------------
9Recommended Reading
10-------------------
11
12Please read `How to write the perfect pull request
13<https://blog.jaraco.com/how-to-write-perfect-pull-request/>`_ for some tips
14on contributing to open source projects. Although the article is not
15authoritative, it was authored by the maintainer of Setuptools, so reflects
16his opinions and will improve the likelihood of acceptance and quality of
17contribution.
18
19------------------
20Project Management
21------------------
22
23Setuptools is maintained primarily in GitHub at `this home
24<https://github.com/pypa/setuptools>`_. Setuptools is maintained under the
25Python Packaging Authority (PyPA) with several core contributors. All bugs
26for Setuptools are filed and the canonical source is maintained in GitHub.
27
28User support and discussions are done through
29`GitHub Discussions <https://github.com/pypa/setuptools/discussions>`_,
30or the issue tracker (for specific issues).
31
32Discussions about development happen on GitHub Discussions or
33the ``setuptools`` channel on `PyPA Discord <https://discord.com/invite/pypa>`_.
34
35-----------------
36Authoring Tickets
37-----------------
38
39Before authoring any source code, it's often prudent to file a ticket
40describing the motivation behind making changes. First search to see if a
41ticket already exists for your issue. If not, create one. Try to think from
42the perspective of the reader. Explain what behavior you expected, what you
43got instead, and what factors might have contributed to the unexpected
44behavior. In GitHub, surround a block of code or traceback with the triple
45backtick "\`\`\`" so that it is formatted nicely.
46
47Filing a ticket provides a forum for justification, discussion, and
48clarification. The ticket provides a record of the purpose for the change and
49any hard decisions that were made. It provides a single place for others to
50reference when trying to understand why the software operates the way it does
51or why certain changes were made.
52
53Setuptools makes extensive use of hyperlinks to tickets in the changelog so
54that system integrators and other users can get a quick summary, but then
55jump to the in-depth discussion about any subject referenced.
56
57---------------------
58Making a pull request
59---------------------
60
61When making a pull request, please
62:ref:`include a short summary of the changes <Adding change notes
63with your PRs>` and a reference to any issue tickets that the PR is
64intended to solve.
65All PRs with code changes should include tests. All changes should
66include a changelog entry.
67
68.. include:: ../../changelog.d/README.rst
69
70-------------------
71Auto-Merge Requests
72-------------------
73
74To support running all code through CI, even lightweight contributions,
75the project employs Mergify to auto-merge pull requests tagged as
76auto-merge.
77
78Use ``hub pull-request -l auto-merge`` to create such a pull request
79from the command line after pushing a new branch.
80
81-------
82Testing
83-------
84
85The primary tests are run using tox.  Make sure you have tox installed,
86and invoke it::
87
88    $ tox
89
90Under continuous integration, additional tests may be run. See the
91``.travis.yml`` file for full details on the tests run under Travis-CI.
92
93-------------------
94Semantic Versioning
95-------------------
96
97Setuptools follows ``semver``.
98
99.. explain value of reflecting meaning in versions.
100
101----------------------
102Building Documentation
103----------------------
104
105Setuptools relies on the `Sphinx`_ system for building documentation.
106The `published documentation`_ is hosted on Read the Docs.
107
108To build the docs locally, use tox::
109
110    $ tox -e docs
111
112.. _Sphinx: http://www.sphinx-doc.org/en/master/
113.. _published documentation: https://setuptools.pypa.io/en/latest/
114
115---------------------
116Vendored Dependencies
117---------------------
118
119Setuptools has some dependencies, but due to `bootstrapping issues
120<https://github.com/pypa/setuptools/issues/980>`_, those dependencies
121cannot be declared as they won't be resolved soon enough to build
122setuptools from source. Eventually, this limitation may be lifted as
123PEP 517/518 reach ubiquitous adoption, but for now, Setuptools
124cannot declare dependencies other than through
125``setuptools/_vendor/vendored.txt`` and
126``pkg_resources/_vendor/vendored.txt``.
127
128All the dependencies specified in these files are "vendorized" using a
129simple Python script ``tools/vendor.py``.
130
131To refresh the dependencies, run the following command::
132
133    $ tox -e vendor
134