[Twisted-Python] Contributing documentation inside CONTRIBUTING repo file

[exarkun at twistedmatrix.com]

On 05:25 pm, adi at roiban.ro wrote:
>On 24 February 2014 21:53, Richard Wall <m-lists at the-moon.net> wrote:
>>On 22 February 2014 02:49, Glyph Lefkowitz <glyph at twistedmatrix.com> 
>>wrote:
><snip>
>>The current new contributors guide is here:
>>https://twistedmatrix.com/trac/wiki/ContributingToTwistedLabs
>>
>>The draft new contributors guide is here:
>>https://twistedmatrix.com/trac/wiki/Contribute (That's the doc which
>>ashfall_ and I were working on)
>
><snip>
>
>Both version are rather verbose for my taste...

The solution to the problem of "There are too many words to read" is not 
to start a new file and start typing new words into it.

The massive sprawl that is our contributor documentation definitely 
needs to be fixed.  I know it's easier to start a fresh document (this 
time it'll work for sure!) but please consider that this strategy may 
actually not produce the best results (it may in fact be the strategy 
that produced the current state of affairs).
>I was looking for a
>quick checklists for contributing with code, which could be included
>in main CONTRIBUTING file.
>It should assume that dev already got the code and has a common sense

"common sense"?  There is no such thing, sorry.  This is sort of an 
irrelevant tangent but I couldn't help commenting on it.
>for contributing to open source projects: create branch, create patch,
>use tickets, use IRC. read code, write tests etc
>
>* Make sure your work has an associated ticket
>* Hack on code, test your code, write tests first :)
>* Once you think you are done, run all tests (maybe have a command to
>run them all):
>  * Check that dev dependencies are install: pip install
>twisted-dev-tools jinja2>=1.0.0 pyflakes>=0.7.3
>  * Check that Python 2.7 tests pass: ./bin/trial twisted
>  * Check that Python 3.3 tests pass: ./admin/run-python3-tests
>  * If you made changes to api reference check that no errors are
>produces and that HTML result looks right: ./bin/admin/build-apidocs
>  * If you made changes to narative documentation check that no errors
>are produced and that HTML result looks good: ./bin/admin/build-docs
>  * Check that no pyflakes errors are generated by your code: pyflakes
>  * Check that twistedchecker did not complain about your code: 
>twistedchecker
>* As for review. Attach diff file to git ticket, set owner to None and
>set 'review' keyword
>* For more details see : WIKI_PAGE

Many of these points are redundant with documentation on one or more 
wiki pages that already exists.  And there are many important things 
that a contributor must know that aren't mentioned here - for example, 
incompatible changes aren't acceptable, all APIs must be documented, 
etc.

It would be excellent to have a comprehensive list of requirements.  I 
strongly suspect that the best way to arrive at this list is to look at 
the existing documentation and remove the redundancies and fix the 
organization.

There may be gaps that need to be filled in.  If so, please fill them 
in.  Creating a new document with a new set of gaps really isn't making 
the situation better.
>
>During review process my patches were rejected since either Pyhon 3.3
>teste were failing, or apidocs was not passing or twistedchecker was
>not passing, but it was not obvious how to do those tests on my
>computer and searching wiki pages did not help... same with pyflakes
>which was only mentioned in ReviewProcess

I know that you've already done a lot of work towards making it easier 
to run these extra build steps locally.  Thank you very much for that!
>
>I think that current wiki pages are very useful, but since they are
>mixed with both policy, best practices and tool usage, it easy for
>them to get out of sync with latest tools using in the development
>process.

Can you give an example of this?  And how will a new document avoid 
exactly the same problem?  Perhaps we *shouldn't* try documenting tool 
usage at all - but instead we should refer to the documentation for 
those tools (which presumably will be kept up to date)?
>
>There are a lot of steps and tools used for validating a patch and
>sadly some checks only work on buildbot.
>I am dedicating my time to improve local testing experience ... and
>maybe also create a help tool to run all tests from a single command.
>
>Once I got more info about contributing to Twisted I will try to
>submit a patch for the main CONTRIBUTING file... but maybe there is a
>better way to help new contributors.

Perhaps this would eventually make a good addition but (to repeat 
myself, sorry) this doesn't seem like a good idea right now.  Until we 
actually have a coherent message to present I don't see the benefit of 
creating yet a new source of slightly conflicting, somewhat incomplete 
information (and one that's harder to edit than a wiki page as a bonus).

Jean-Paul