| 123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125 |
- ================================
- 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
- <http://blog.jaraco.com/2014/04/how-to-write-perfect-pull-request.html>`_
- 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 IRC
- (Freenode) at #pypa-dev.
- -----------------
- 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.
- For posterity, the old `Bitbucket mirror
- <https://bitbucket.org/pypa/setuptools>`_ is available.
- -------
- Testing
- -------
- The primary tests are run using py.test. To run the tests::
- $ python setup.py test
- Or install py.test into your environment and run ``PYTHONPATH=. py.test``
- or ``python -m pytest``.
- 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 and in
- particular the ``build_sphinx`` distutils command. To build the
- documentation, invoke::
- python setup.py build_sphinx
- from the root of the repository. Setuptools will download a compatible
- build of Sphinx and any requisite plugins and then build the
- documentation in the build/sphinx directory.
- Setuptools does not support invoking the doc builder from the docs/
- directory as some tools expect.
|
