On 05:25 pm, adi@roiban.ro wrote:
On 24 February 2014 21:53, Richard Wall <m-lists@the-moon.net> wrote:
On 22 February 2014 02:49, Glyph Lefkowitz <glyph@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