Re: Policy decision needed about Documentation/snippets/new

[Graham Percival]

On Wed, Jul 18, 2012 at 03:08:55PM +0200, John Mandereau wrote:
> Note that in the case you change a single or a couple of snippets in
> Documentation/snippets/new and don't want to update everything by
> downloading and unpacking a tarball from LSR website, there are
> currently contradictory instructions:
> * one page tells to run makelsr.py
> http://lilypond.org/doc/v2.15/Documentation/contributor/adding-and-editing-snippets

This is the correct option.


> 1) Current behaviour (broken and not well documented, but can be easily
> fixed)
> 
> .ly files in Documentation/snippets/new are not used directly by
> documentation build, they are run through makelsr.py, which adds a "Do
> not edit" comment and convert-ly the file into Documentation/snippets.
> Any fix or change to Documentation/snippets/new that isn't concerned
> with syntax changes could be done by making the change simultaneously in
> Documentation/snippets and Documentation/snippets/new, but we wouldn't
> document it and require instead to run makelsr.py without arguments
> after a fresh "make" (without "make doc") and with LILYPOND_BUILD_DIR
> set correctly.

Yes, this is the correct option [for now].

> The advantage of this alternative is that the only changes to be made
> are a few lines in makelsr.py and the CG.  Its disadvantage is that
> developers may edit just Documentation/snippets/new, thus leaving
> changes untested for a few days or weeks; for example, IIUC
> 4ab6e4df934e57c51dbbdbf2c209273c6cb5b888 (May 9 2012) 
> was not used in doc build until 9fe18536fe333c167fe1bd87f76a30b20f603dd0
> (June 19 2012), and missed release 2.15.39. There are other older
> examples of this.

The LSR editor should be running makelsr.py at least once a week.
A high-achiever could even work it into the release instructions
for added safety, although that of course may require a few rounds
before it's completely correct (because I refuse to let the
release checklist to get out-of-date with the "reality on the
ground" like other parts of the CG).

> 2) Other behaviour
> 
> In doc build, makesnippets runs in both Documentation/snippets and
> Documentation/snippets/out, and lilypond-book looks for .ly files in
> Documentation/snippets/new/out before Documentation/snippets/out.
> Snippets in Documentation/snippets/new should no longer be
> copied/handled by makelsr.py to Documentation/snippets.

I thought your big makelsr patch already did this?  Anyway, I'm
not opposed to it, but I think the first step is to ensure that
the CG presents a working set of steps.

For that reason, I think we should document the first option, and
if/when the build supports this alternate behaviour, change the CG
then.

- Graham