Re: contributing instructions are misleading!

[Carl Peterson]

On Wed, Dec 11, 2013 at 9:54 PM, Graham Percival <address@hidden> wrote:

On Wed, Dec 11, 2013 at 01:48:54PM +0100, Janek Warchoł wrote:
> PS ccing to Graham because he might be interested to know that
> Someone(TM) is doing Something(TM) to help new contributors!

Sorry, this awoke Grumpy Graham.

Reorganizing the CG is very much a "something should be done, this
is something, so can somebody else do this thing".

Is there any solid evidence that a serious contributor finds it
difficult to skip over section 2.1 if it's not relevant?

Speaking as the "new contributor" whose experience provoked Janek's indignation, here's my perception of things. Just to give my background, while I've not done much direct application (C++, etc.) programming, I spend most of my day in my "real job" looking at Microsoft Access databases and writing VBA code for those. In my spare time, whatever that is, and with some part time jobs, I do quite a bit of web programming, including writing a records management system in PHP. I'm familiar with version control, though until looking seriously at LilyPond, my VCS of choice was Subversion.

To try to recount the process I went through awhile back, I did install LilyDev at first, when I was wanting to virtualize my dev environment on my iMac. Later, I brought out the Linux box I had set up with Debian a year ago and went through the process of updating it so that I could build LilyPond. I was able to connect to git with minimal fuss, and currently use the lily-git.tcl tool to handle commits and patches.

All that said, where things got interesting for me was when I wanted to figure out how to submit my patch. Following through the directions in 2.2 (lily-git), I got to this text:

> Send patch files to the appropriate place:
>

> * If you have a mentor, send it to them via email.
> * New contributors should send the patch attached to an email to address@hidden. Please add “[PATCH]” to the subject line.
> * Translators should send patches to address@hidden.
> * More experienced contributors should upload the patch for web-based review. This requires additional software and use of the command-line; see Uploading a patch for review.

At first, I sent the patch to Janek, because the area I was working on (Metafont) was an area he had done some work in and while he doesn't claim to be an expert, I felt that he was someone worth going to, more or less a "mentor" (and yes, I realize that word and the relationship is defined more concretely elsewhere, but at this point, I don't really see any "mentoring" going on, which begs the question of whether it should even be mentioned). After taking a look at the patch, he let me know that I really needed to submit the patch myself. So I went to the second option, since I think I meet the definition of "new contributor." I told Janek that and copied in the text above in an email, which precipitated what most of you all have seen.

I don't know that the organization of the CG is *necessarily* wrong (except where processes are obsolete for various reasons), but I think that instead of providing one concrete workflow for contributing, there are a lot of options offered and described in more or less detail in different places, which can be confusing for anyone who isn't an "experienced developer" (in the sense of being familiar with git and other such tools). I felt like I was going around in circles and never able to find the same information the same way across multiple times trying to look the information up.

Cheers,

Carl P.