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