| ================================ |
| 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 |