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