diff --git a/docs/development/developer-guide.rst b/docs/development/developer-guide.rst deleted file mode 100644 index ae1b58f2f5..0000000000 --- a/docs/development/developer-guide.rst +++ /dev/null @@ -1,188 +0,0 @@ -================================ -Developer's Guide for Setuptools -================================ - -If you want to know more about contributing on Setuptools, this is the place. - - -------------------- -Recommended Reading -------------------- - -Please read `How to write the 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 -`_. 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 -`GitHub Discussions `_, -or the issue tracker (for specific issues). - -Discussions about development happen on GitHub Discussions or -the ``setuptools`` channel on `PyPA Discord `_. - ------------------ -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 -:ref:`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. - -.. include:: ../../newsfragments/README.rst - -------------------- -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: https://www.sphinx-doc.org/en/master/ -.. _published documentation: https://setuptools.pypa.io/en/latest/ - ---------------------- -Vendored Dependencies ---------------------- - -Setuptools has some dependencies, but due to `bootstrapping issues -`_, 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``. - -All the dependencies specified in these files are "vendorized" using a -simple Python script ``tools/vendor.py``. - -To refresh the dependencies, run the following command:: - - $ tox -e vendor - - ------------------------------------- -Code conventions and other practices ------------------------------------- - -Setuptools utilizes the `skeleton `_ -framework as a foundation for sharing reusable maintenance tasks -across different projects in the ecosystem. - -This also means that the project adheres to the same coding conventions -and other practices described in the `skeleton documentation -`_. - -Moreover, changes in the code base should be kept as compatible as possible -to ``skeleton`` to avoid merge conflicts, or accidental regressions on -periodical merges. - -Finally, the ``setuptools/_distutils`` directory should not be modified -directly when contributing to the ``setuptools`` project. -Instead, this directory is maintained as a separated project in -https://github.com/pypa/distutils, and periodically merged into ``setuptools``. - - ----------------- -Type annotations ----------------- - -Most standards and best practices are enforced by -`Ruff `_'s ``ANN2``, ``FA``, ``PYI``, ``UP`` -and ``YTT`` rules. - -Explicit return types have to be added for typed public functions whose -parameters are *all* annotated. This is enforced by ``ANN2``, but it's worth noting -that this is due to mypy inferring ``Any`` even for simple return types. Mypy also -doesn't count functions with missing parameter annotations as "typed". (see -`python/mypy#4409 `_, -`python/mypy#10149 `_ and -`python/mypy#6646 `_). -Otherwise, return annotations can be omitted to reduce verbosity, -especially for complex return types. - -Instead of typing an explicit return type annotation as -``Generator[..., None, None]``, we'll prefer using an ``Iterator`` as it is more -concise and conceptually easier to deal with. Returning a ``Generator`` with no -``yield`` type or ``send`` type can sometimes be considered as exposing -implementation details. See -`Y058 `_. - -Avoid importing private type-checking-only symbols. These are often -`typeshed `_ internal details and are not -guaranteed to be stable. -Importing from ``_typeshed`` or ``typing_extensions`` is fine, but if you find -yourself importing the same symbol in ``TYPE_CHECKING`` blocks a lot, consider -implementing an alias directly in ``setuptools``. diff --git a/docs/development/index.rst b/docs/development/index.rst deleted file mode 100644 index 7ee52361ec..0000000000 --- a/docs/development/index.rst +++ /dev/null @@ -1,34 +0,0 @@ -------------------------- -Development on Setuptools -------------------------- - -Setuptools is maintained by the Python community under the Python Packaging -Authority (PyPA) and led by Jason R. Coombs. - -This document describes the process by which Setuptools is developed. -This document assumes the reader has some passing familiarity with -*using* setuptools, the ``pkg_resources`` module, and pip. It -does not attempt to explain basic concepts like inter-project -dependencies, nor does it contain detailed lexical syntax for most -file formats. Neither does it explain concepts like "namespace -packages" or "resources" in any detail, as all of these subjects are -covered at length in the setuptools developer's guide and the -``pkg_resources`` reference manual. - -Instead, this is **internal** documentation for how those concepts and -features are *implemented* in concrete terms. It is intended for people -who are working on the setuptools code base, who want to be able to -troubleshoot setuptools problems, want to write code that reads the file -formats involved, or want to otherwise tinker with setuptools-generated -files and directories. - -Note, however, that these are all internal implementation details and -are therefore subject to change; stick to the published API if you don't -want to be responsible for keeping your code from breaking when -setuptools changes. You have been warned. - -.. toctree:: - :maxdepth: 1 - - developer-guide - releases diff --git a/docs/development/releases.rst b/docs/development/releases.rst deleted file mode 100644 index 35b415c265..0000000000 --- a/docs/development/releases.rst +++ /dev/null @@ -1,37 +0,0 @@ -=============== -Release Process -=============== - -In order to allow for rapid, predictable releases, Setuptools uses a -mechanical technique for releases, enacted on tagged commits by -continuous integration. - -To finalize a release, run ``tox -e finalize``, review, then push -the changes. - -If tests pass, the release will be uploaded to PyPI. - -Release Frequency ------------------ - -Some have asked why Setuptools is released so frequently. Because Setuptools -uses a mechanical release process, it's very easy to make releases whenever the -code is stable (tests are passing). As a result, the philosophy is to release -early and often. - -While some find the frequent releases somewhat surprising, they only empower -the user. Although releases are made frequently, users can choose the frequency -at which they use those releases. If instead Setuptools contributions were only -released in batches, the user would be constrained to only use Setuptools when -those official releases were made. With frequent releases, the user can govern -exactly how often he wishes to update. - -Frequent releases also then obviate the need for dev or beta releases in most -cases. Because releases are made early and often, bugs are discovered and -corrected quickly, in many cases before other users have yet to encounter them. - -Release Managers ----------------- - -Additionally, anyone with push access to the master branch has access to cut -releases.