diff options
| -rw-r--r-- | CHANGES.txt | 10 | ||||
| -rw-r--r-- | DEVGUIDE.txt | 23 | ||||
| -rw-r--r-- | docs/developer-guide.txt | 92 | ||||
| -rw-r--r-- | docs/development.txt | 2 |
4 files changed, 93 insertions, 34 deletions
diff --git a/CHANGES.txt b/CHANGES.txt index 5ebe6f1c..9344ccbb 100644 --- a/CHANGES.txt +++ b/CHANGES.txt @@ -3,6 +3,14 @@ CHANGES ======= --- +5.2 +--- + +* Added a `Developer Guide + <https://pythonhosted.org/setuptools/developer-guide.html>`_ to the official + documentation. + +--- 5.1 --- @@ -28,6 +36,8 @@ CHANGES --- * Issue #218: Re-release of 3.8.1 to signal that it supersedes 4.x. +* Incidentally, script templates were updated not to include the triple-quote + escaping. ------------------------- 3.7.1 and 3.8.1 and 4.0.1 diff --git a/DEVGUIDE.txt b/DEVGUIDE.txt index f96d8115..066a3a6b 100644 --- a/DEVGUIDE.txt +++ b/DEVGUIDE.txt @@ -1,22 +1 @@ -============================ -Quick notes for contributors -============================ - -Setuptools is developed using the DVCS Mercurial. - -Grab the code at bitbucket:: - - $ hg clone https://bitbucket.org/pypa/setuptools - -If you want to contribute changes, we recommend you fork the repository on -bitbucket, commit the changes to your repository, and then make a pull request -on bitbucket. If you make some changes, don't forget to: - -- add a note in CHANGES.txt - -Please commit bug-fixes against the current maintenance branch and new -features to the default branch. - -You can run the tests via:: - - $ python setup.py test +The canonical development guide can be found in docs/developer-guide.txt. diff --git a/docs/developer-guide.txt b/docs/developer-guide.txt index fbee5e67..651e6be8 100644 --- a/docs/developer-guide.txt +++ b/docs/developer-guide.txt @@ -8,26 +8,96 @@ If you want to know more about contributing on Setuptools, this is the place. .. contents:: **Table of Contents** ----------------------- -Repository and Tracker ----------------------- +------------------- +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 Bitbucket at `this home +<https://bitbucket.org/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 Bitbucket. -... +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. -.. git mirror +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 Bitbucket, 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 Bitbucket:: + + $ hg clone https://bitbucket.org/pypa/setuptools + +If you want to contribute changes, we recommend you fork the repository on +Bitbucket, commit the changes to your repository, and then make a pull request +on Bitbucket. If you make some changes, don't forget to: + +- add a note in CHANGES.txt + +Please commit all changes in the 'default' 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. + +Setuptools also maintains an unofficial `Git mirror in Github +<https://github.com/jaraco/setuptools>`_. Contributors are welcome to submit +pull requests here, but because they are not integrated with the Bitbucket +Issue tracker, linking pull requests to tickets is more difficult. The +Continuous Integration tests that validate every release are run from this +mirror. + +------- +Testing +------- + +The primary tests are run using py.test. To run the tests:: + + $ python setup.py ptr ------------------------- -Submitting Pull Requests ------------------------- +Or install py.test into your environment and run ``py.test``. -Use Mercurial bookmarks or Git branches. Use incremental commits. Minimize -stylistic changes. +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 diff --git a/docs/development.txt b/docs/development.txt index e35ba39b..6fe30f6e 100644 --- a/docs/development.txt +++ b/docs/development.txt @@ -30,7 +30,7 @@ setuptools changes. You have been warned. .. toctree:: :maxdepth: 1 - .. developer-guide + developer-guide formats releases |