Documentation/contributor/lsr-work.itexi

   1 @c -*- coding: us-ascii; mode: texinfo; -*-
   2 @node LSR work
   3 @chapter LSR work
   4
   5 @menu
   6 * Introduction to LSR::
   7 * Adding and editing snippets::
   8 * Approving snippets::
   9 * LSR to Git::
  10 * Fixing snippets in LilyPond sources::
  11 * Updating LSR to a new version::
  12 @end menu
  13
  14
  15 @node Introduction to LSR
  16 @section Introduction to LSR
  17
  18 The
  19 @uref{http://lsr.dsi.unimi.it/, LilyPond Snippet Repository (LSR)}
  20 is a collection of lilypond examples.  A subset of these examples
  21 are automatically imported into the documentation, making it easy
  22 for users to contribute to the docs without learning Git and
  23 Texinfo.
  24
  25
  26 @node Adding and editing snippets
  27 @section Adding and editing snippets
  28
  29 @subheading General guidelines
  30
  31 When you create (or find!) a nice snippet, if it supported by LilyPond
  32 version running on LSR, please add it to LSR.  Go to
  33 @uref{http://lsr.dsi.unimi.it/, LSR} and log in -- if you haven't
  34 already, create an account.  Follow the instructions on the website.
  35 These instructions also explain how to modify existing snippets.
  36
  37 If you think the snippet is particularly informative and you think it
  38 should be included in the documentation, tag it with @qq{docs} and one
  39 or more other categories, or ask somebody who has editing permissions to
  40 do it on the development list.
  41
  42 Please make sure that the lilypond code follows the guidelines in
  43 @ref{LilyPond formatting}.
  44
  45 If a new snippet created for documentation purposes compiles with
  46 LilyPond version currently on LSR, it should be added to LSR, and a
  47 reference to the snippet should be added to the documentation.
  48
  49 If the new snippet uses new features that are not available in the
  50 current LSR version, the snippet should be added to @file{input/new} and
  51 a reference should be added to the manual.
  52
  53 Snippets created or updated in @file{input/new} should be copied to
  54 @file{input/lsr} by invoking at top of the source tree
  55
  56 @example
  57 scripts/auxiliar/makelsr.py
  58 @end example
  59
  60 Be sure that @command{make doc} runs successfully before submitting a
  61 patch, to prevent breaking compilation.
  62
  63 @subheading Formatting snippets in @file{input/new}
  64
  65 When adding a file to this directory, please start the file with
  66
  67 @example
  68 \version "2.x.y"
  69 \header @{
  70   lsrtags = "rhythms,expressive-marks"  % use existing LSR tags other than
  71 %   'docs'; see makelsr.py for the list of tags used to sort snippets.
  72   texidoc = "This code demonstrates ..."  % this will be formated by Texinfo
  73   doctitle = "Snippet title"  % please put this at the end so that
  74     the '% begin verbatim' mark is added correctly by makelsr.py.
  75 @}
  76 @end example
  77
  78 and name the file @file{snippet-title.ly}.
  79
  80
  81 @node Approving snippets
  82 @section Approving snippets
  83
  84 The main task of LSR editors is approving snippets.  To find a list of
  85 unapproved snippets, log into @uref{http://lsr.dsi.unimi.it/, LSR} and
  86 select @qq{No} from the dropdown menu to the right of the word
  87 @qq{Approved} at the bottom of the interface, then click
  88 @qq{Enable filter}.
  89
  90 Check each snippet:
  91
  92 @enumerate
  93
  94 @item
  95 Does the snippet make sense and does what the author claims that
  96 it does?  If you think the snippet is particularly helpful, add
  97 the @qq{docs} tag and at least one other tag.
  98
  99 @item
 100 If the snippet is tagged with @qq{docs}, check to see if it
 101 matches our guidelines for @ref{LilyPond formatting}.
 102
 103 @item
 104 If the snippet uses scheme, check that everything looks good and
 105 there are no security risks.
 106
 107 @warning{Somebody could sneak a @code{#'(system "rm -rf /")}
 108 command into our source tree if you do not do this!  Take this
 109 step @strong{VERY SERIOUSLY}.}
 110
 111 @end enumerate
 112
 113
 114 @node LSR to Git
 115 @section LSR to Git
 116
 117 @enumerate
 118
 119 @item
 120 Make sure that @command{convert-ly} and @command{lilypond} commands in
 121 current PATH are in a bleeding edge version -- latest release from
 122 master branch, or even better a fresh snapshot from Git master branch.
 123
 124 @item
 125 From the top source directory, run:
 126
 127 @example
 128 wget http://lsr.dsi.unimi.it/download/lsr-snippets-docs-@var{YYYY-MM-DD}.tar.gz
 129 tar -xzf lsr-snippets-docs-@var{YYYY-MM-DD}.tar.gz
 130 scripts/auxiliar/makelsr.py lsr-snippets-docs-@var{YYYY-MM-DD}
 131 @end example
 132
 133 @noindent
 134 where @var{YYYY-MM-DD} is the current date, e.g. 2009-02-28.
 135
 136 @item
 137 Follow the instructions printed on the console to manually check for
 138 unsafe files.
 139
 140 @warning{Somebody could sneak a @code{#'(system "rm -rf /")}
 141 command into our source tree if you do not do this!  Take this
 142 step @strong{VERY SERIOUSLY}.}
 143
 144 @item
 145 Do a git add / commit / push.
 146
 147 @end enumerate
 148
 149 Note that whenever there is one snippet from @file{input/new} and the
 150 other from LSR with the same file name, the one from @file{input/new}
 151 will be copied by @command{makelsr.py}.
 152
 153
 154 @node Fixing snippets in LilyPond sources
 155 @section Fixing snippets in LilyPond sources
 156
 157 In case some snippet from @file{input/lsr} cause the documentation
 158 compilation to fail, the following steps should be followed to fix it
 159 reliably.
 160
 161 @enumerate
 162
 163 @item
 164 Look up the snippet filename @file{@var{foo}.ly} in the error output
 165 or log, then fix the file @file{input/lsr/@var{foo}.ly} to make the
 166 documentation build succesfully.
 167
 168 @item
 169 Determine where it comes from by looking at its first line, e.g. run
 170
 171 @example
 172 head -1 input/lsr/@var{foo}.ly
 173 @end example
 174
 175 @item
 176 @strong{In case the snippet comes from LSR}, apply the fix to the
 177 snippet in LSR and send a notification email to a LSR editor with CC
 178 to the development list -- see @ref{Adding and editing snippets}.  The
 179 failure may sometimes not be caused by the snippet in LSR but by the
 180 syntax conversion made by @command{convert-ly}; in this case, try to
 181 fix @command{convert-ly} or report the problem on the development
 182 list, then run @command{makelsr.py} again, see @ref{LSR to Git}.  In
 183 some cases, when some features has been introduced or vastly changed
 184 so it requires (or takes significant advantage of) important changes
 185 in the snippet, it is simpler and recommended to write a new version
 186 of the snippet in @file{input/new}, then run @command{makelsr.py}.
 187
 188 @item
 189 @strong{In case the snippet comes from} @file{input/new}, apply in
 190 @file{input/new/@var{foo}.ly} the same fix you did in
 191 @file{input/lsr/@var{foo}.ly}.  In case the build failure was caused
 192 by a translation string, you may have to fix
 193 @file{input/texidocs/@var{foo}.texidoc} instead.
 194
 195 @item
 196 In any case, commit all changes to Git.
 197
 198 @end enumerate
 199
 200
 201
 202 @node Updating LSR to a new version
 203 @section Updating LSR to a new version
 204
 205 To update LSR, perform the following steps:
 206
 207 @enumerate
 208
 209 @item
 210 Download the latest snippet tarball, extract it, and run
 211 @code{convert-ly} on all files using the command-line option
 212 @code{--to=VERSION} to ensure snippets are updated to the
 213 correct stable version.
 214
 215 @item
 216 Copy relevant snippets (i.e., snippets whose version is equal to or
 217 less than the new version of LilyPond) from @file{input/new/} into
 218 the tarball.
 219
 220 You must not rename any files during this, or the next, stage.
 221
 222 @item
 223 Verify that all files compile with the new version of LilyPond,
 224 ideally without any warnings or errors.  To ease the process,
 225 you may use the shell script that appears after this list.
 226
 227 Due to the workload involved, we @emph{do not} require that you
 228 verify that all snippets produce the expected output.  If you
 229 happen to notice any such snippets and can fix them, great; but as
 230 long as all snippets compile, don't delay this step due to some
 231 weird output.  If a snippet is broken, the hordes of willing
 232 web-2.0 volunteers will fix it.  It's not our problem.
 233
 234 @item
 235 Create a tarball and send it back to Sebastiano.
 236
 237 @item
 238 When LSR has been updated, download another snippet tarball,
 239 verify that the relevant snippets from @file{input/new/} were
 240 included, then delete those snippets from @file{input/new/}.
 241
 242 @end enumerate
 243
 244
 245 Here is a shell script to run all @code{.ly} files in a directory
 246 and redirect terminal output to text files, which are then
 247 searched for the word "failed" to see which snippets do not compile.
 248
 249 @example
 250 #!/bin/bash
 251
 252 for LILYFILE in *.ly
 253 do
 254   STEM=$(basename "$LILYFILE" .ly)
 255   echo "running $LILYFILE..."
 256   lilypond --format=png -ddelete-intermediate-files "$LILYFILE" >& "$STEM".txt
 257 done
 258
 259 grep failed *.txt
 260 @end example