Re: improving the CG

[Graham Percival]

On Mon, Dec 28, 2009 at 5:43 PM, Colin Campbell <address@hidden> wrote:
> A one of the newer of noobs, I can testify that the biggest problems I'm
> having with git are not seeing how git becomes aware of changes I might
> make: do I edit from within { git gui/gitk/lilycontrib } or use an external
> editor,

Start: blindly copy&paste from:
- 1.1.2
- 1.1.3

Then, before you start working each day, you blindly copy&paste the
first item from
- 1.2.2

Then you edit whatever file with whatever editor you want (graphical,
command-line, raw manipulation of bits on the hard drive by holding a
magnet).  When you're finished, you blindly copy&paste the first bit
from
- 1.3.1
and then write a short commit message.


Trust me, I spent literally years working this way (although I had
those commands in a text file, since the CG didn't exist).

> and more importantly, *what* do I edit: where are the bits and
> pieces which eventually become lilypond, what parts of the source should I
> look at and where/how do I find them?

Have you looked at
http://lilypond.org/doc/v2.13/Documentation/web/help-us

?
That's the intended "starting off" position.

> I'd been beating my head against trying to grok the build
> mechanism in its entirety,

Don't.  Really, don't.  I spent even longer without having a clue how
it worked.  I've spent the past year slowly learning bits and pieces
of it, and it's not a pleasant task.  I spend literally an hour
figuring out how to make a one-line fix.  I think I've spent about 100
hours this year on the build system, and I still don't grok it.

"make doc" (or "make EXTERNAL_BINARY doc") should just work.  If it
doesn't work, let us know ASAP and I'll take a look at it.  This isn't
anything that a new doc contributor should have to mess with.


Also, I'm sorry I asked you to see how much you could get done without
asking questions -- some new contributors ask me to repeat things
which are in the CG, and you caught me in a less-than-ideal mood.
You've clearly demonstrated that you do your homework before asking
questions, so in the future please ask me about anything that's
stumped you for more than 10 minutes.  My answer might be "ick, I'll
need to fix that; please wait" or "don't try to understand that stuff;
just copy&paste XYZ", but at least you'll know where you stand.  :)

(actually, the 10-minute rule is a good idea in general; I should add
_that_ to the CG)

Cheers,
- Graham