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
  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 @item
 110 If the snippet uses scheme, check that everything looks good and
 111 there are no security risks.
 112
 113 @warning{Somebody could sneak a @code{#'(system "rm -rf /")}
 114 command into our source tree if you do not do this!  Take this
 115 step @strong{VERY SERIOUSLY}.}
 116
 117 @end enumerate
 118
 119
 120 @node LSR to Git
 121 @section LSR to Git
 122
 123 @enumerate
 124
 125 @item
 126 Make sure that @command{convert-ly} and @command{lilypond} commands in
 127 current PATH are in a bleeding edge version -- latest release from
 128 master branch, or even better a fresh snapshot from Git master branch.
 129
 130 @item
 131 From the top source directory, run:
 132
 133 @example
 134 wget http://lsr.dsi.unimi.it/download/lsr-snippets-docs-@var{YYYY-MM-DD}.tar.gz
 135 tar -xzf lsr-snippets-docs-@var{YYYY-MM-DD}.tar.gz
 136 scripts/auxiliar/makelsr.py lsr-snippets-docs-@var{YYYY-MM-DD}
 137 @end example
 138
 139 @noindent
 140 where @var{YYYY-MM-DD} is the current date, e.g. 2009-02-28.
 141
 142 @item
 143 Follow the instructions printed on the console to manually check for
 144 unsafe files.
 145
 146 @warning{Somebody could sneak a @code{#'(system "rm -rf /")}
 147 command into our source tree if you do not do this!  Take this
 148 step @strong{VERY SERIOUSLY}.}
 149
 150 @item
 151 Do a git add / commit / push.
 152
 153 @end enumerate
 154
 155 Note that whenever there is one snippet from
 156 @file{Documentation/snippets/new} and the other from LSR with the same
 157 file name, the one from @file{Documentation/snippets/new} will be copied
 158 by @command{makelsr.py}.
 159
 160
 161 @node Fixing snippets in LilyPond sources
 162 @section Fixing snippets in LilyPond sources
 163
 164 In case some snippet from @file{Documentation/snippets} causes the
 165 documentation compilation to fail, the following steps should be
 166 followed to fix it reliably.
 167
 168 @enumerate
 169
 170 @item
 171 Look up the snippet filename @file{@var{foo}.ly} in the error output
 172 or log, then fix the file @file{Documentation/snippets/@var{foo}.ly} to make the
 173 documentation build succesfully.
 174
 175 @item
 176 Determine where it comes from by looking at its first line, e.g. run
 177
 178 @example
 179 head -1 Documentation/snippets/@var{foo}.ly
 180 @end example
 181
 182 @item
 183 @strong{In case the snippet comes from LSR}, apply the fix to the
 184 snippet in LSR and send a notification email to a LSR editor with CC to
 185 the development list -- see @ref{Adding and editing snippets}.  The
 186 failure may sometimes not be caused by the snippet in LSR but by the
 187 syntax conversion made by @command{convert-ly}; in this case, try to fix
 188 @command{convert-ly} or report the problem on the development list, then
 189 run @command{makelsr.py} again, see @ref{LSR to Git}.  In some cases,
 190 when some features has been introduced or vastly changed so it requires
 191 (or takes significant advantage of) important changes in the snippet, it
 192 is simpler and recommended to write a new version of the snippet in
 193 @file{Documentation/snippets/new}, then run @command{makelsr.py}.
 194
 195 @item
 196 @strong{In case the snippet comes from}
 197 @file{Documentation/snippets/new}, apply in
 198 @file{Documentation/snippets/new/@var{foo}.ly} the same fix you did in
 199 @file{Documentation/snippets/@var{foo}.ly}.  In case the build failure
 200 was caused by a translation string, you may have to fix
 201 @file{input/texidocs/@var{foo}.texidoc} instead.
 202
 203 @item
 204 In any case, commit all changes to Git.
 205
 206 @end enumerate
 207
 208
 209
 210 @node Updating LSR to a new version
 211 @section Updating LSR to a new version
 212
 213 To update LSR, perform the following steps:
 214
 215 @enumerate
 216
 217 @item
 218 Download the latest snippet tarball, extract it, and run
 219 @code{convert-ly} on all files using the command-line option
 220 @code{--to=VERSION} to ensure snippets are updated to the
 221 correct stable version.
 222
 223 @item
 224 Copy relevant snippets (i.e., snippets whose version is equal to or less
 225 than the new version of LilyPond) from
 226 @file{Documentation/snippets/new/} into the tarball.
 227
 228 You must not rename any files during this, or the next, stage.
 229
 230 @item
 231 Verify that all files compile with the new version of LilyPond,
 232 ideally without any warnings or errors.  To ease the process,
 233 you may use the shell script that appears after this list.
 234
 235 Due to the workload involved, we @emph{do not} require that you
 236 verify that all snippets produce the expected output.  If you
 237 happen to notice any such snippets and can fix them, great; but as
 238 long as all snippets compile, don't delay this step due to some
 239 weird output.  If a snippet is broken, the hordes of willing
 240 web-2.0 volunteers will fix it.  It's not our problem.
 241
 242 @item
 243 Create a tarball and send it back to Sebastiano.
 244
 245 @item
 246 When LSR has been updated, download another snippet tarball, verify that
 247 the relevant snippets from @file{Documentation/snippets/new/} were
 248 included, then delete those snippets from
 249 @file{Documentation/snippets/new/}.
 250
 251 @end enumerate
 252
 253
 254 Here is a shell script to run all @code{.ly} files in a directory
 255 and redirect terminal output to text files, which are then
 256 searched for the word "failed" to see which snippets do not compile.
 257
 258 @example
 259 #!/bin/bash
 260
 261 for LILYFILE in *.ly
 262 do
 263   STEM=$(basename "$LILYFILE" .ly)
 264   echo "running $LILYFILE..."
 265   lilypond --format=png -ddelete-intermediate-files "$LILYFILE" >& "$STEM".txt
 266 done
 267
 268 grep failed *.txt
 269 @end example