RFC: CONTRIBUTING.md

[sumnerevans]

Consider this a Request for Comments. I've done my best to describe the current policies regarding contributions to this repository. My understanding is most likely flawed, so please provide feedback and corrections to this document. Let's keep everything civil in this thread.

[jackrosenthal]

Already done. See the master branch.

[jackrosenthal]

P.S. I have no issues with your contribution guidelines, I just think they are too complicated and nobody is going to read them all. Keep it short and sweet.

Also, this is a Python project, so it should use reStructuredText format.

Maybe a potential guideline to add is "if you assign a task to someone else but it turns out you want to do it, contact them and let them know you are doing it first". It would prevent situations like this. (and this is not the first time this has happened with you. IIRC, you told me in that PR to write it in the CONTRIBUTING file.)

[sumnerevans]

@jackrosenthal , along with that guideline we should add that "if you begin working on something, create an issue and assign it to yourself" and "if you want someone else to do something, create an issue and assign it to them".

I'll admit, this was a reaction to our previous discussion. I see how you saw that as an implicit assignment, but I didn't know that you took it as such. Both of us are guilty of not doing this, and I think adding these guidelines will help assure this situation doesn't happen again.

I agree, 1030 words is overkill, but I do think that your CONTRIBUTING.rst is lacking direction on some things you are passionate about, namely semantic HTML usage. Most people use <strong> and <em> for everything, regardless of whether or not it is for display purposes. You are in the minority, so that should be specified in the guidelines. There are some other things that I think we should integrate from this into your document. I'm modifying this PR right now.

[jackrosenthal]

I agree, 1030 words is overkill, but I do think that your CONTRIBUTING.rst is lacking direction on some things you are passionate about, namely semantic HTML usage. Most people use <strong> and <em> for everything, regardless of whether or not it is for display purposes.

These are small nit-picky things that can be resolved in the code review process. This is not important to include in the CONTRIBUTING file since things like this can be quickly resolved (versus, requiring things work without JavaScripts is a major thing to know from a software design standpoint), and if we start adding things like this then the file will grow over-complicated too fast.

[jackrosenthal]

tl;dr: the CONTRIBUTING file is a "how to contribute" file, not a "requirements for contributions" file. It gives general guidance on how to add code to this repo, not a specification on what exactly that code has to look like. It's intentionally vague (enough).

[jackrosenthal]

OK to delete this branch?

[sumnerevans]

Yes