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