Recommended Reading¶

Please readHow to write the perfect pull request for some tipson contributing to open source projects. Although the article is notauthoritative, it was authored by the maintainer of Setuptools, so reflectshis opinions and will improve the likelihood of acceptance and quality ofcontribution.

Project Management¶

Setuptools is maintained primarily in GitHub atthis home. Setuptools is maintained under thePython Packaging Authority (PyPA) with several core contributors. All bugsfor Setuptools are filed and the canonical source is maintained in GitHub.

User support and discussions are done throughGitHub Discussions,or the issue tracker (for specific issues).

Discussions about development happen on GitHub Discussions orthesetuptools channel onPyPA Discord.

Authoring Tickets¶

Before authoring any source code, it’s often prudent to file a ticketdescribing the motivation behind making changes. First search to see if aticket already exists for your issue. If not, create one. Try to think fromthe perspective of the reader. Explain what behavior you expected, what yougot instead, and what factors might have contributed to the unexpectedbehavior. In GitHub, surround a block of code or traceback with the triplebacktick “```” so that it is formatted nicely.

Filing a ticket provides a forum for justification, discussion, andclarification. The ticket provides a record of the purpose for the change andany hard decisions that were made. It provides a single place for others toreference when trying to understand why the software operates the way it doesor why certain changes were made.

Setuptools makes extensive use of hyperlinks to tickets in the changelog sothat system integrators and other users can get a quick summary, but thenjump to the in-depth discussion about any subject referenced.

Making a pull request¶

When making a pull request, pleaseinclude a short summary of the changes and a reference to any issue tickets that the PR isintended to solve.All PRs with code changes should include tests. All changes shouldinclude a changelog entry.

Added a``:user:`` role to Sphinx config -- by:user:`webknjaz`

Added``towncrier`` for changelog management -- by:user:`pganssle`

When pip is imported as part of a build, leave:py:mod:`distutils`patched -- by:user:`jaraco`

Auto-Merge Requests¶

To support running all code through CI, even lightweight contributions,the project employs Mergify to auto-merge pull requests tagged asauto-merge.

Usehubpull-request-lauto-merge to create such a pull requestfrom 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 followssemver.

Building Documentation¶

Setuptools relies on theSphinx system for building documentation.Thepublished documentation is hosted on Read the Docs.

To build the docs locally, use tox:

$ tox -e docs

Vendored Dependencies¶

Setuptools has some dependencies, but due tobootstrapping issues, those dependenciescannot be declared as they won’t be resolved soon enough to buildsetuptools from source. Eventually, this limitation may be lifted asPEP 517/518 reach ubiquitous adoption, but for now, Setuptoolscannot declare dependencies other than throughsetuptools/_vendor/vendored.txt andpkg_resources/_vendor/vendored.txt.

All the dependencies specified in these files are “vendorized” using asimple Python scripttools/vendor.py.

To refresh the dependencies, run the following command:

$ tox -e vendor

Code conventions and other practices¶

Setuptools utilizes theskeletonframework as a foundation for sharing reusable maintenance tasksacross different projects in the ecosystem.

This also means that the project adheres to the same coding conventionsand other practices described in theskeleton documentation.

Moreover, changes in the code base should be kept as compatible as possibletoskeleton to avoid merge conflicts, or accidental regressions onperiodical merges.

Finally, thesetuptools/_distutils directory should not be modifieddirectly when contributing to thesetuptools project.Instead, this directory is maintained as a separated project inhttps://github.com/pypa/distutils, and periodically merged intosetuptools.

Type annotations¶

Most standards and best practices are enforced byRuff’sANN2,FA,PYI,UPandYTT rules.

Explicit return types have to be added for typed public functions whoseparameters areall annotated. This is enforced byANN2, but it’s worth notingthat this is due to mypy inferringAny even for simple return types. Mypy alsodoesn’t count functions with missing parameter annotations as “typed”. (seepython/mypy#4409,python/mypy#10149 andpython/mypy#6646).Otherwise, return annotations can be omitted to reduce verbosity,especially for complex return types.

Instead of typing an explicit return type annotation asGenerator[...,None,None], we’ll prefer using anIterator as it is moreconcise and conceptually easier to deal with. Returning aGenerator with noyield type orsend type can sometimes be considered as exposingimplementation details. SeeY058.

Avoid importing private type-checking-only symbols. These are oftentypeshed internal details and are notguaranteed to be stable.Importing from_typeshed ortyping_extensions is fine, but if you findyourself importing the same symbol inTYPE_CHECKING blocks a lot, considerimplementing an alias directly insetuptools.