Complete CONTRIBUTING.md (or create tests/README.md) #564

Activity

1. asottile

   added

   cleanup

   on Jul 18, 2017
2. asottile commented on Jul 18, 2017

   

   asottile

   on Jul 18, 2017

   Last edited by asottile

   Member

   More actions

   First I don't think we should split the two files, it's pretty unlikely that someone is going to read either of them in the first place :)

   I've collected a few other repositories for some guidance:

   • pip/pypa:
     • has a contributing.md and a docs/development.rst
     • their CONTRIBUTING.md is largely a link to their code of conduct -- there haven't been any issues yet of code of conduct, I don't think this is important at this point in the project
     • Their developing file contains a short blurb about how to run the tests -- but mostly assumes you know how to use the tools
   • unbit/uwsgi - nothing at all, hmm
   • requests/requests
     • contributing.md and docs/dev/contributing.rst
     • similar to pip, their contributing.md largely links to their code of conduct and the other contributing file
     • their contributing.rst mentions tox / py.test not at all, assuming the reader knows how to use these tools or that the reader can peruse the tool's documentation to figure that out
   • pytest-dev/pytest
     • A single contributing.md
     • This has the full gamut of code of conduct and test running
     • Again, they don't really go super into detail on duplicating tox / pytest docs

   I didn't really have time to find other large python projects but my general idea from those couple that I perused is to avoid duplicating the upstream tooling's documentation -- generally keeping it simple :)

   Hmm, my thoughts on this and feel free to disagree (I'll go section by section based on your PR):

   targeted environments

   I think we can largely leave this out, this information is in four common places already: setup.py, tox.ini, .travis.yml, appveyor.yml

   installing the test environment

   I don't really want to write directions for installing python on $N different systems. Also the current documentation doesn't necessarily work (without first adding ppa:deadsnakes (shameless plug, I help maintain 😆)) for all debian-based distributions. If this were added, I could see other PRs for adding instructions to install python on macos / windows / etc. and I think people are better off just googling that (or going to python.org).

   Running the tests

   A lot of this section is good, but a lot of it is duplicated in CONTRIBUTING.md, if anything gets kept it'd come out of this section 👍

   I'm not sure the bit about git configuration is super necessary, I think people's initial thought should be "the tests are broken" => make an issue. I think the reason your feature continued to have problems was you didn't pull the upstream after I made the fixes, heh.

   Let me know your thoughts :)
3. asottile commented on Oct 10, 2017

   

   asottile

   on Oct 10, 2017

   Member

   More actions

   For now I'm going to close this, feel free to add to the CONTRIBUTING.md file in this repository :)
4. asottile

   closed this as completedon Oct 10, 2017