Re: Contributor Guide "volunteers" needed

[Graham Percival]

On Sun, Jan 18, 2009 at 03:47:34PM +0100, Maximilian Albert wrote:
> 2009/1/18 Graham Percival <address@hidden>:
> 
> > - can somebody maoing check the maoing git commands in CG 1
> >  already?  Either somebody with a big internet connection, or
> 
> Done. All of them work fine (but se the comment on 1.3.1 below).

By "work fine", I also want to know that:
- future pulls work with simply "git pull" or "git pull origin"
  (whatever is listed in that section)
- creating patches works with whatever the command is
  (whether that's "git-format-patch HEAD or MASTER or whatever)
- "git push" or "git push origin" or whatever works for users with
  commit ability.

This isn't directed at you (I don't think you can test point #3),
but I include them here so that other people don't think this job
is finished.  :)

> nor did I figure out what the correct
> commands in section 1.1.4 should be.

I include this here for emphasis.


> Two comments regarding the CG in general:
> 
> 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).

The original makefile used --split=section; I suggest that this be
used again.  When the CG got merged into master, AFAIK it started
to use the same doc build system as we use for the LM and NR.


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

Yeah, I copied it directly from one of the IIRC 5 different README
files we have floating around.  As I said, I wasn't going to
bother editing that section.  :)

Fortunately, Trevor and Jonathan have "volunteered" to handle CG
1, so this is their responsibility now.  :):)

Cheers,
- Graham