On Aug 28, 2011, at 11:45 AM, Graham Percival wrote: > On Sun, Aug 28, 2011 at 11:29:28AM +0200, m...@apollinemike.com 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 > lilypond-devel@gnu.org > https://lists.gnu.org/mailman/listinfo/lilypond-devel > _______________________________________________ lilypond-devel mailing list lilypond-devel@gnu.org https://lists.gnu.org/mailman/listinfo/lilypond-devel
