X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=Documentation%2Fcontributor%2Flsr-work.itexi;h=31bf9c4168654f90690832625d3a08716550513e;hb=0ea80a5e850c6114d1ba7dc4cfd81d5a45d9604a;hp=be4493838a6d1de902163928d7f88ac092aaaf7c;hpb=820bbcbc38981f5a1866f291cdf40042ea686db0;p=lilypond.git diff --git a/Documentation/contributor/lsr-work.itexi b/Documentation/contributor/lsr-work.itexi index be4493838a..31bf9c4168 100644 --- a/Documentation/contributor/lsr-work.itexi +++ b/Documentation/contributor/lsr-work.itexi @@ -17,7 +17,7 @@ @section Introduction to LSR The -@uref{http://lsr.dsi.unimi.it/, LilyPond Snippet Repository (LSR)} +@uref{http://lsr.di.unimi.it/, LilyPond Snippet Repository (LSR)} is a collection of lilypond examples. A subset of these examples are automatically imported into the documentation, making it easy for users to contribute to the docs without learning Git and @@ -31,7 +31,7 @@ Texinfo. When you create (or find!) a nice snippet, if it is supported by the LilyPond version running on the LSR, please add it to the LSR. -Go to @uref{http://lsr.dsi.unimi.it/, LSR} and log in -- if you haven't +Go to @uref{http://lsr.di.unimi.it/, LSR} and log in -- if you haven't already, create an account. Follow the instructions on the website. These instructions also explain how to modify existing snippets. @@ -64,17 +64,6 @@ source tree scripts/auxiliar/makelsr.py @end example -@noindent -@command{makelsr} also copies translated texidoc fields and snippet titles into -snippets in @file{Documentation/snippets}. Note: this, in turn, could -make the translated texidoc fields to appear as out of sync when you -run @code{make check-translation}, if the originals changed from the -last translation update, even if the translations are also updated; -see @ref{Documentation translation maintenance} for details about -updating the docs; in particular, see @ref{Updating translation -committishes} to learn how to mark these translated fields as fully -updated. - Be sure that @command{make doc} runs successfully before submitting a patch, to prevent breaking compilation. @@ -119,7 +108,7 @@ filename. @section Approving snippets The main task of LSR editors is approving snippets. To find a list of -unapproved snippets, log into @uref{http://lsr.dsi.unimi.it/, LSR} and +unapproved snippets, log into @uref{http://lsr.di.unimi.it/, LSR} and select @qq{No} from the dropdown menu to the right of the word @qq{Approved} at the bottom of the interface, then click @qq{Enable filter}. @@ -186,10 +175,11 @@ the source code from @enumerate @item -Make sure that @command{convert-ly} script and the -@command{lilypond} binary are a -bleeding edge version -- the latest release or even better, a fresh -snapshot from Git master. +Make sure that @command{convert-ly} script and the @command{lilypond} +binary are a bleeding edge version -- the latest release or even +better, a fresh snapshot from Git master, with the environment +variable @code{LILYPOND_BUILD_DIR} correctly set up, see +@ref{Environment variables}. @item Start by creating a list of updated snippets from your local @@ -200,22 +190,34 @@ 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 +other than minor changes. 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: +Next, download the updated snippets and run @command{makelsr.py} +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} +wget http://lsr.di.unimi.it/download/lsr-snippets-docs-`date +%F`.tar.gz +tar -xzf lsr-snippets-docs-`date +%F`.tar.gz +make -C $LILYPOND_BUILD_DIR +scripts/auxiliar/makelsr.py lsr-snippets-docs-`date +%F` @end smallexample @noindent -where @var{YYYY-MM-DD} is the current date, e.g. 2011-12-25. +where @command{date +%F} gives the current date in format +@var{YYYY-MM-DD} (the snippets archive is usually generated around +03:50 CET, you may want to use @command{date -d yesterday +%F} +instead, depending on your time zone and the time you run this +commands sequence). @command{make} is included in this sequence so +that @command{makelsr} can run @command{lilypond} and +@command{convert-ly} versions that match current source tree; you can +select different binaries if desired or needed, to see options for +this do + +@smallexample +scripts/auxiliar/makelsr.py --help +@end smallexample @item Follow the instructions printed on the console to manually check for @@ -232,13 +234,13 @@ 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. +As the console says, @command{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 @@ -248,7 +250,8 @@ If there is any doubt about any of the files, you are strongly advised to run a review on Rietveld. @item -If a Review is not needed, commit the changes and push to staging. +If a Review is not needed, commit the changes and push to +@code{staging}. @end enumerate @@ -273,10 +276,11 @@ or log, then fix the file @file{Documentation/snippets/@var{foo}.ly} to make the documentation build successfully. @item -Determine where it comes from by looking at its first line, e.g. run +Determine where it comes from by looking at its first two lines, +e.g. run @example -head -1 Documentation/snippets/@var{foo}.ly +head -2 Documentation/snippets/@var{foo}.ly @end example @item @@ -293,12 +297,21 @@ is simpler and recommended to write a new version of the snippet in @file{Documentation/snippets/new}, then run @command{makelsr.py}. @item -@strong{If the snippet comes from} -@file{Documentation/snippets/new}, apply the same fix in -@file{Documentation/snippets/new/@var{foo}.ly} that you did in -@file{Documentation/snippets/@var{foo}.ly}. If the build failure -was caused by a translation string, you may have to fix -@file{input/texidocs/@var{foo}.texidoc} instead. +@strong{If the snippet comes from} @file{Documentation/snippets/new}, +apply the fix in @file{Documentation/snippets/new/@var{foo}.ly}, then +run @command{makelsr.py} without argument from top of the source tree: + +@example +scripts/auxiliar/makelsr.py +@end example + +Then, inspect @file{Documentation/snippets/@var{foo}.ly} to check that +the fix has been well propagated. + +If the build failure was caused by a translation string, you may have +to fix some @file{Documentation/@var{lang}/texidocs/@var{foo}.texidoc} +instead; in case the build failure comes only from translation +strings, it is not needed to run @command{makelsr.py}. @item When you've done, commit your changes to Git and ensure they're @@ -347,7 +360,7 @@ updating the binary running the LSR. @item Download the latest snippet tarball from -@uref{http://lsr.dsi.unimi.it/download/} and extract it. +@uref{http://lsr.di.unimi.it/download/} and extract it. The relevant files can be found in the @file{all} subdirectory. Make sure your shell is using an English language version, for example @code{LANG=en_US}, then run @command{convert-ly} on all