Re: Make doc fails

[address@hidden]

On Aug 28, 2011, at 11:45 AM, Graham Percival wrote:

> On Sun, Aug 28, 2011 at 11:29:28AM +0200, address@hidden wrote:
>> 
>> Please let me know what I could do to prevent this from happening again
> 
> Since you were editing documentation, I would have liked you to
> have:
> 1. touch Documentation/*.te??
>   (this tells make to check all manuals to see if they need
> recompiling)
> 2. make doc
> 
> If you'd done that, you would have seen the build fail.
> 

Ok, will do from here on out.  With respect to the discussion about flags, I 
did not know that scripts/auxiliar/makelsr.py was not part of the automated 
build process, and now that I do, I will make sure to run it when making any 
doc changes.
I think that your idea of having some way to automatically check the docs is 
great.  It is important that developers, as best as possible, update the docs 
to work after their syntax changes.  However, without automatic checks, it is 
difficult.

In my opinion, the best way to do this would be to have a catalog of properties 
and public functions used in the docs.  Whenever a developer:

1)  Eliminates a function; or
2)  Eliminates a property; or
3)  Changes the return value of the property (i.e. ly:grob? becomes boolean?),

make doc will be scanned and the build will crash if;

1) The eliminated function still exists in the docs; or
2) The eliminated property still exists in the docs; or
3) The return value requested in the docs no longer reflects the new return 
value of the property.

As for syntax changes, I agree with you about a general rule being 
inappropriate and that avoiding them is very important.  I think that the above 
type of doc checking is likely the best way to handle syntax changes, and 
otherwise, the review process can be the forum for deciding their 
appropriateness.  In the case of my most recent two pushes (Flag and Stem 
changes), the syntax changes were the subject of the discussion surrounding the 
patches, so I think that the review process did its job.

Cheers,
MS

> 
>> As for the convert-ly rule, I was under the impression that
>> these rules were pushed on a version-to-version basis, and all
>> syntax changes were written as one rule before the rolling of
>> the next version.  The last time I added one was because the
>> versions had changed and a rule didn't exist for the version
>> during which a commit of mine happened.  Please let me know how
>> you want me to go about this in the future - if there could be
>> an entry in the CG about it, that'd help a great deal.
> 
> Hmm, we don't really have a set policy for this -- and with the
> patch/review/push cycle sometimes taking more than a month, it's a
> tricky issue.
> 
> For now, let's just say that syntax changes are really, really
> icky, and if you absolutely need to do one, we'll talk about how
> to do it safely in that specific instance.  I don't want to try to
> make a general rule at the moment.
> 
> Cheers,
> - Graham
> 
> _______________________________________________
> lilypond-devel mailing list
> address@hidden
> https://lists.gnu.org/mailman/listinfo/lilypond-devel
>