[Twisted-Python] Contributing documentation inside CONTRIBUTING repo file

[Adi Roiban]

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... 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
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

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 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.

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.

-- 
Adi Roiban