Sorry, my mistake. PostgreSQL doesn't use upstart. $ sudo /etc/init.d/postgresql restart -Derrick -----Original Message----- From: twisted-python-bounces@twistedmatrix.com [mailto:twisted-python-bounces@twistedmatrix.com] On Behalf Of exarkun@twistedmatrix.com Sent: Thursday, February 20, 2014 10:13 AM To: Twisted general discussion Subject: Re: [Twisted-Python] Contributing documentation inside CONTRIBUTING repo file On 02:55 pm, adi@roiban.ro wrote:

Hi.

Right now CONTRIBUTING file from twisted repo sends developers to: https://twistedmatrix.com/trac/wiki/ContributingToTwistedLabs

What do you think about having basic contributing documentation inside the repo? I am talking about these 2 pages:

https://twistedmatrix.com/trac/wiki/BasicGuideToContributingCode https://twistedmatrix.com/trac/wiki/TwistedDevelopment

Commiters Check list can be left on the wiki page: https://twistedmatrix.com/trac/wiki/CommitterCheckList

--------

I think that those pages are very important to assist new developers in creating a successful patch (ie one that is merged without to much ping-pong)

Even if I now have wiki edit page, I don't have the courage to change the wiki page (for example to add information about twistedchecker or how to build the new docs).

Changing a file and submitting for review feels more comfortable.

Also, developers could always refer to that file from inside their preferred text editor.

There is currently an effort to re-organize the contributor documentation underway. Given its fragile state, I wouldn't want to disturb it sending work off in a different direction. On the other hand, if you'd like to take over and complete it, feel free to take whatever direction you like. :) Either way I suggest you try to coordinate with the folks working on that. Jean-Paul

Is there someone review-ul changes on the wiki pages?

I hope people read changes made to the wiki. I usually do. Jean-Paul _______________________________________________ Twisted-Python mailing list Twisted-Python@twistedmatrix.com http://twistedmatrix.com/cgi-bin/mailman/listinfo/twisted-python

On 20 February 2014 17:13, <exarkun@twistedmatrix.com> wrote:

On 02:55 pm, adi@roiban.ro wrote:

...

Hi.

Right now CONTRIBUTING file from twisted repo sends developers to: https://twistedmatrix.com/trac/wiki/ContributingToTwistedLabs

What do you think about having basic contributing documentation inside the repo? I am talking about these 2 pages:

https://twistedmatrix.com/trac/wiki/BasicGuideToContributingCode https://twistedmatrix.com/trac/wiki/TwistedDevelopment

Commiters Check list can be left on the wiki page: https://twistedmatrix.com/trac/wiki/CommitterCheckList

--------

I think that those pages are very important to assist new developers in creating a successful patch (ie one that is merged without to much ping-pong)

Even if I now have wiki edit page, I don't have the courage to change the wiki page (for example to add information about twistedchecker or how to build the new docs).

Changing a file and submitting for review feels more comfortable.

Also, developers could always refer to that file from inside their preferred text editor.

There is currently an effort to re-organize the contributor documentation underway. Given its fragile state, I wouldn't want to disturb it sending work off in a different direction. On the other hand, if you'd like to take over and complete it, feel free to take whatever direction you like. :) Either way I suggest you try to coordinate with the folks working on that.

Thanks for the reply. I am happy to coordinate with folks working on contributor documentation re-organization, but I have idea how exactly I am supposed to do that and who is working on this task. Thanks! -- Adi Roiban

On 22 February 2014 02:49, Glyph Lefkowitz <glyph@twistedmatrix.com> wrote: <snip>

Richard Wall and Ashwini Oruganti are two of the people working on this, but to the best of my knowledge this effort is unfortunately mostly stalled right now. If neither of them respond promptly to this thread, I think it would be best to consider that effort defunct and proceed with whatever changes you want to make.

The timeline report on wiki changes <http://twistedmatrix.com/trac/timeline?from=02%2F21%2F2014&daysback=90&wiki=on&update=Update> suggests that no work has been done on this in over 90 days, which seems like an appropriate window beyond which superseding it is fair game :).

Hi, Sorry for not replying sooner. I was reminded about this by another potential new contributor, navneet_, in #twisted-dev today. I did do some work on this last year, building on Ashwini's work. I've pasted an IRC conversation where Ashwini explained the goal of the new new- contributor documentation. The gist is that there should be a *single* page which guides new contributors through the process of contributing their first patch. We think that one of the main problems with the current new-contributor documentation is that it requires the reader to click and read too many separate documents which are spread between the wiki and the sphinx documentation...with no decent navigation links between the pages. 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) You can see my changes to that document using the history view: https://twistedmatrix.com/trac/wiki/Contribute?action=history I didn't get very far, I think I got distracted making some improvements to the trac "attach a patch" page which seemed like a more natural place to document the patch requirements which I'd originall intended to put in the Contribute page. * https://github.com/twisted-infra/trac-config/pull/2 I also had plans to add Google search links to the trac search page, but never got round to it. I thought that might make it easier for new contributors to find existing issues before filing new tickets. Iccha Sethi wrote a nice blog post documenting the Twisted new contributor experience: http://www.icchasethi.com/my-experiences-contributing-to-twisted/ I personally would like to see all the new contributor documentation migrated out of the wiki and into version controlled ReST documentation. Django documentation is usually a good inspiration but it looks like they do link to lots of different documents. But perhaps that's less of a problem because it's all sphinx based. * https://docs.djangoproject.com/en/1.6/internals/contributing/ Anyway, I'm still happy to help improve the new contributor documentation, but probably haven't got the time to co-ordinate the effort. -RichardW. {{{ less .znc/moddata/log/rwall_freenode_#twisted-dev_20130827.log [06:48:48] <ashfall_> rwall: Thanks for the email, it reminded me I have aan incomplete wiki page to finish [08:29:03] <rwall> ashfall_: Good morning. Can I help you finish it off? I'll review it if you like. [08:30:51] * rwall reads https://twistedmatrix.com/trac/wiki/Contribute [08:31:45] * rwall and https://twistedmatrix.com/trac/wiki/ContributingToTwistedLabs [08:32:13] <rwall> and https://twistedmatrix.com/trac/wiki/ContributionIdeas [10:33:36] <rwall> tomprince: I wrote some words for inclusion in the new ticket page (well I copied most of it from Django page.) I mentioned it in lp:twisted-website but should I create a ticket in Github twisted-infra instead? [10:47:21] <rwall> I created https://github.com/twisted-infra/trac-config/issues/1 [12:53:21] <ashfall_> rwall: I'm not sure it's ready to the point of review yet, but feel free to work on it/make or suggest changes if you like (in f act, the sooner it's done the better, I'm glad you showed interest :) [12:55:22] <ashfall_> rwall: I was trying to organize all the information we have about contributing, and then expanding upon it - the basic aim was t o put everything together, if not all the text, at least all the links to relevant text [12:56:11] <ashfall_> and then to remove redundant information [12:56:17] <rwall> ashfall_: But there is already https://twistedmatrix.com/trac/wiki/ContributingToTwistedLabs. The new page didn't look *that* diffe rent. [12:57:48] <ashfall_> indeed. I started from there, but what's slightly different is the links to various other places (I didn't want to edit in that page, because I wasn't confident about how soon I'll complete this) [12:58:55] <ashfall_> rwall: Either way, currently the page's like an index. Next I was planning to organize it, and see how it goes from there [12:58:55] <rwall> Ok I see. [13:01:57] <ashfall_> So I guess what I'm saying is, feel free to finish what I started, if you feel like it you can even ignore the page completely a nd edit something that already exists, as long as the end result is a page that gives one all the information needed to contribute - "one page that ha s it all" was the goal iirc [13:04:10] <rwall> I think "one page" is a good goal. Ok. I might have a go at editing your new page. [13:04:33] <ashfall_> Thanks :) [13:04:34] <exarkun> Maybe the goal should be written at the top of the page [13:05:20] <rwall> Ok. I'll do that first. }}}

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

On 17 March 2014 02:08, Glyph <glyph@twistedmatrix.com> wrote:

On Mar 16, 2014, at 1:48 PM, exarkun@twistedmatrix.com wrote:

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 don't have a lot to comment on this but it really bears repeating.

This problem is also not unique to Twisted; see also <https://xkcd.com/927/>.

Agreed and understood. I will try to work on updating the current wiki pages. Thanks! -- Adi Roiban