[Top][All Lists]

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Re: Policy decision needed about Documentation/snippets/new

From: Graham Percival
Subject: Re: Policy decision needed about Documentation/snippets/new
Date: Wed, 18 Jul 2012 14:18:43 +0100
User-agent: Mutt/1.5.21 (2010-09-15)

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

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

- Graham

reply via email to

[Prev in Thread] Current Thread [Next in Thread]