Re: Contributor Guide "volunteers" needed

[Maximilian Albert]

2009/1/18 Graham Percival <address@hidden>:

> HIGH PRIORITY:
> - can somebody maoing check the maoing git commands in CG 1
>  already?  Either somebody with a big internet connection, or
>  somebody who knows git so intimiately that he can state with
>  absolute certainty that the commands work.

Done. All of them work fine (but se the comment on 1.3.1 below). Note
that I only performed the commands marked with a FIXME (in sections
1.1.2 - 1.1.4) and had a look at the other ones which didn't involve a
lot of sophisticated stuff (I didn't bother with GUB, for example). I
didn't do any further testing, nor did I figure out what the correct
commands in section 1.1.4 should be. Also, I couldn't review section
1.5 as I'm on Linux exclusively.

Two comments regarding the CG in general:

1) The link on the intro page of the CG, i.e., at

     
http://www.kainhofer.com/~lilypond/Documentation/devel/contrib-guide/index.html

which points to the "one big page" version is broken, and so is the
link to the PDF version (although both links work fine from one level
higher, i.e., from

     http://www.kainhofer.com/~lilypond/Documentation/devel/index.html

).

2) I very much like well-structured documents. However, I find it
slightly annoying to have to descend _three_ levels before getting to
the first piece of text. Two levels would be acceptable IMHO, but
personally I'd prefer if section 1.1 (say) could be displayed on a
single page comprising subsections 1.1.1 - 1.1.7 (still including the
table of contents, of course, so that they can be quickly navigated
to). I find it difficult to have to go back after reading just a
single short paragraph (or even sentence).


And here are a few questions/comments on specific sections:

1.2.2: One precautionary question: Do unexpected things happen if the
user is working on a branch other than master (and has local changes)?
Should git pull origin only be performed on the master branch? I'm not
familiar enough with git internals to judge this.

1.2.3: I'd add something along the lines of "In files where conflicts
occurred, the critical parts are marked with <<<<<<< ... ======= ...
>>>>>>>." Of course, there is a lot more to say, but this might
already help.

1.2.4: I know that you (Graham) said that you won't bother with that
section, but anyway: Paragraph No. 5 refers to a "git fetch command
above" which was never mentioned before. The same presumably applies
to the "git checkout command above" in the next paragraph (which I
guess doesn't refer to the commands in sections 1.1.2 - 1.1.4 where
"git checkout" was used, too). Moreover, the last paragraph refers to
"this README" when there is no README document there.

1.3.1: AFAICT the second command "git-format-patch HEAD" doesn't do
anything because HEAD is the latest commit the user did, i.e., it
already includes his changes. Thus there is no diff which could be
produced. I suppose it should be changed to "git-format-patch master"
instead (or whatever branch he is working on). Am I missing something?
git gurus please correct me.

Cheers,
Max