[Twisted-Python] Contributing documentation inside CONTRIBUTING repo file

[Richard Wall]

On 22 February 2014 02:49, Glyph Lefkowitz <glyph at 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.
}}}