You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
116 lines
3.9 KiB
116 lines
3.9 KiB
================================
|
|
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.
|
|
|
|
-----------
|
|
Source Code
|
|
-----------
|
|
|
|
Grab the code at Github::
|
|
|
|
$ git checkout https://github.com/pypa/setuptools
|
|
|
|
If you want to contribute changes, we recommend you fork the repository on
|
|
Github, commit the changes to your repository, and then make a pull request
|
|
on Github. If you make some changes, don't forget to:
|
|
|
|
- add a note in CHANGES.rst
|
|
|
|
Please commit all changes in the 'master' branch against the latest available
|
|
commit or for bug-fixes, against an earlier commit or release in which the
|
|
bug occurred.
|
|
|
|
If you find yourself working on more than one issue at a time, Setuptools
|
|
generally prefers Git-style branches, so use Mercurial bookmarks or Git
|
|
branches or multiple forks to maintain separate efforts.
|
|
|
|
The Continuous Integration tests that validate every release are run
|
|
from this repository.
|
|
|
|
-------
|
|
Testing
|
|
-------
|
|
|
|
The primary tests are run using tox. To run the tests, first make
|
|
sure you have tox installed, then 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.
|
|
To accommodate RTD, docs must be built from the docs/ directory.
|
|
|
|
To build them, you need to have installed the requirements specified
|
|
in docs/requirements.txt. One way to do this is to use rwt:
|
|
|
|
setuptools/docs$ python -m rwt -r requirements.txt -- -m sphinx . html
|