On 05:25 pm, a...@roiban.ro wrote:
On 24 February 2014 21:53, Richard Wall <m-li...@the-moon.net> wrote:
On 22 February 2014 02:49, Glyph Lefkowitz <gl...@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
_______________________________________________
Twisted-Python mailing list
Twisted-Python@twistedmatrix.com
http://twistedmatrix.com/cgi-bin/mailman/listinfo/twisted-python
