CG: Use latest convert-ly for LSR updates (fix 2346)

[lilypond.git] / Documentation / contributor / lsr-work.itexi

diff --git a/Documentation/contributor/lsr-work.itexi b/Documentation/contributor/lsr-work.itexi
index 27349b3625c4092a65ffeae9150b4ae1d877ad90..9cc0d1805df515b35729d3c54a769e48463f0603 100644 (file)
--- a/Documentation/contributor/lsr-work.itexi
+++ b/Documentation/contributor/lsr-work.itexi
@@ -94,7 +94,7 @@ This code demonstrates ...
 @}
 @end example
 
-\noindent
+@noindent
 and name the file @file{snippet-title.ly}.
 
 
@@ -141,32 +141,68 @@ step @strong{VERY SERIOUSLY}.}
 @enumerate
 
 @item
-Make sure that @command{convert-ly} and @command{lilypond} commands in
-current PATH are in a bleeding edge version -- latest release from
-master branch, or even better a fresh snapshot from Git master branch.
+Make sure that @command{convert-ly} and @command{lilypond} are a
+bleeding edge version -- the latest release or even better a fresh
+snapshot from Git master.
 
 @item
-From the top source directory, run:
+Start by creating a list of updated snippets from your local
+repository.  From the top source directory, run:
 
 @example
+scripts/auxiliar/makelsr.py
+@end example
+
+Commit the changes and make a patch.  Check the patch has nothing
+other than minor changes - in particular changes to the commitish
+for translations.  If all is good and you're confident in what
+you've done, this can be pushed directly to staging.
+
+@item
+Next, download the updated snippets and run makelsr against them.
+From the top source directory, run:
+
+@smallexample
 wget http://lsr.dsi.unimi.it/download/lsr-snippets-docs-@var{YYYY-MM-DD}.tar.gz
 tar -xzf lsr-snippets-docs-@var{YYYY-MM-DD}.tar.gz
 scripts/auxiliar/makelsr.py lsr-snippets-docs-@var{YYYY-MM-DD}
-@end example
+@end smallexample
 
 @noindent
-where @var{YYYY-MM-DD} is the current date, e.g. 2009-02-28.
+where @var{YYYY-MM-DD} is the current date, e.g. 2011-12-25.
 
 @item
 Follow the instructions printed on the console to manually check for
-unsafe files.
+unsafe files.  These are:
+
+@example
+Unsafe files printed in lsr-unsafe.txt: CHECK MANUALLY!
+  git add Documentation/snippets/*.ly
+  xargs git diff HEAD < lsr-unsafe.txt
+@end example
+
+First, it's important to check for any added files and add them to
+the files git is tracking.  Run @code{git status} and look
+carefully to see if files have been added.  If so, add them with
+@code{git add}.
+
+As the console says, makelsr creates a list of possibly unsafe
+files in @file{lsr-unsafe.txt} by running @code{lilypond} against each
+snippet using the @code{-dsafe} switch.  This list can be quite
+long.  However, by using the command @code{xargs git diff HEAD < lsr-unsafe.txt}
+git will take that list and check whether any of the snippets are
+different from the snippet already in master.  If any is different
+it must be checked manually VERY CAREFULLY.
 
 @warning{Somebody could sneak a @code{#'(system "rm -rf /")}
 command into our source tree if you do not do this!  Take this
 step @strong{VERY SERIOUSLY}.}
 
+If there is any doubt about any of the files, you are strongly
+advised to run a review on Rietveld.
+
 @item
-Do a git add / commit / push.
+If a Review is not needed, commit the changes and push to staging.
 
 @end enumerate
 
@@ -260,9 +296,34 @@ To update LSR, perform the following steps:
 @item
 Download the latest snippet tarball, extract it, and run
 @code{convert-ly} on all files using the command-line option
-@code{--to=VERSION} to ensure snippets are updated to the
+@option{--to=@var{version}} to ensure snippets are updated to the
 correct stable version.
 
+Make sure you use @code{convert-ly} from the latest available release to gain
+all advantages from the latest converting-rules-updates.
+
+Example:
+
+@itemize
+
+@item
+LSR-version: 2.12.2
+
+@item
+intended LSR-update to 2.14.2
+
+@item
+latest release 2.15.30
+
+@end itemize
+
+Use @code{convert-ly} from 2.15.30 and the following terminal
+command for all files:
+
+@example
+convert-ly -e -t2.14.2 *.ly
+@end example
+
 @item
 Copy relevant snippets (i.e., snippets whose version is equal to or less
 than the new version of LilyPond) from
@@ -298,7 +359,7 @@ Here is a shell script to run all @file{.ly} files in a directory
 and redirect terminal output to text files, which are then
 searched for the word "failed" to see which snippets do not compile.
 
-@example
+@smallexample
 #!/bin/bash
 
 for LILYFILE in *.ly
@@ -309,4 +370,4 @@ do
 done
 
 grep failed *.txt
-@end example
+@end smallexample