Documentation/contributor/lsr-work.itexi

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