[Twisted-Python] Contributing documentation inside CONTRIBUTING repo file

Glyph glyph at twistedmatrix.com
Sun Mar 16 18:08:57 MDT 2014


On Mar 16, 2014, at 1:48 PM, exarkun at 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/>.

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


I think this tangent is actually totally relevant.  Potential contributors to open source overall are a very diverse audience with a widely divergent backgrounds.  Twisted, in particular, attracts an especially idiosyncratic group, because Twisted runs in a really wide array of environments and supports a really wide array of protocols.  If you wanted to do the "normal thing" you'd be contributing to Django, not Twisted.

Also, keep in mind that for many developers, even today, Twisted is their first open source contribution experience.  Therefore there's no particular reason to believe that they would have any idea how to submit patches, or write tests, or that those things are needed.  It may make sense to make there be an easy way to skip over these basics, but they definitely need to be present.

-glyph
-------------- next part --------------
An HTML attachment was scrubbed...
URL: </pipermail/twisted-python/attachments/20140316/f383621c/attachment-0002.html>


More information about the Twisted-Python mailing list