diff options
| -rw-r--r-- | docs/developer-guide.txt | 27 |
1 files changed, 21 insertions, 6 deletions
diff --git a/docs/developer-guide.txt b/docs/developer-guide.txt index c6f78d9a..651e6be8 100644 --- a/docs/developer-guide.txt +++ b/docs/developer-guide.txt @@ -35,6 +35,27 @@ issues, through the distutils-sig mailing list, or on IRC (Freenode) at 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 @@ -78,12 +99,6 @@ Or install py.test into your environment and run ``py.test``. Under continuous integration, additional tests may be run. See the ``.travis.yml`` file for full details on the tests run under Travis-CI. ------------------ -Authoring Tickets ------------------ - -... - ------------------- Semantic Versioning ------------------- |