Documentation/devel/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 @end menu
  12
  13
  14 @node Introduction to LSR
  15 @section Introduction to LSR
  16
  17 The
  18 @uref{http://lsr.dsi.unimi.it/, LilyPond Snippet Repository (LSR)}
  19 is a collection of lilypond examples.  A subset of these examples
  20 are automatically imported into the documentation, making it easy
  21 for users to contribute to the docs without learning Git and
  22 Texinfo.
  23
  24
  25 @node Adding and editing snippets
  26 @section Adding and editing snippets
  27
  28 @subheading General guidelines
  29
  30 When you create (or find!) a nice snippet, if it supported by LilyPond
  31 version running on LSR, please add it to LSR.  Go to
  32 @uref{http://lsr.dsi.unimi.it/, LSR} and log in -- if you haven't
  33 already, create an account.  Follow the instructions on the website.
  34 These instructions also explain how to modify existing snippets.
  35
  36 If you think the snippet is particularly informative and you think it
  37 should be included in the documentation, tag it with @qq{docs} and one
  38 or more other categories, or ask somebody who has editing permissions to
  39 do it on the development list.
  40
  41 Please make sure that the lilypond code follows the guidelines in
  42 @ref{LilyPond formatting}.
  43
  44 If a new snippet created for documentation purposes compiles with
  45 LilyPond version currently on LSR, it should be added to LSR, and a
  46 reference to the snippet should be added to the documentation.
  47
  48 If the new snippet uses new features that are not available in the
  49 current LSR version, the snippet should be added to @file{input/new} and
  50 a reference should be added to the manual.
  51
  52 Snippets created or updated in @file{input/new} should be copied to
  53 @file{input/lsr} by invoking at top of the source tree
  54
  55 @example
  56 scripts/auxiliar/makelsr.py
  57 @end example
  58
  59 Be sure that @command{make web} runs successfully before submitting a
  60 patch, to prevent breaking compilation.
  61
  62 @subheading Formatting snippets in @file{input/new}
  63
  64 When adding a file to this directory, please start the file with
  65
  66 @example
  67 \version "2.x.y"
  68 \header @{
  69   lsrtags = "rhythms,expressive-marks"  % use existing LSR tags other than
  70 %   'docs'; see makelsr.py for the list of tags used to sort snippets.
  71   texidoc = "This code demonstrates ..."  % this will be formated by Texinfo
  72   doctitle = "Snippet title"  % please put this at the end so that
  73     the '% begin verbatim' mark is added correctly by makelsr.py.
  74 @}
  75 @end example
  76
  77 and name the file @file{snippet-title.ly}.
  78
  79
  80 @node Approving snippets
  81 @section Approving snippets
  82
  83 The main task of LSR editors is approving snippets.  To find a list of
  84 unapproved snippets, log into @uref{http://lsr.dsi.unimi.it/, LSR} and
  85 select @qq{No} from the dropdown menu to the right of the word
  86 @qq{Approved} at the bottom of the interface, then click
  87 @qq{Enable filter}.
  88
  89 Check each snippet:
  90
  91 @enumerate
  92
  93 @item
  94 Does the snippet make sense and does what the author claims that
  95 it does?  If you think the snippet is particularly helpful, add
  96 the @qq{docs} tag and at least one other tag.
  97
  98 @item
  99 If the snippet is tagged with @qq{docs}, check to see if it
 100 matches our guidelines for @ref{LilyPond formatting}.
 101
 102 @item
 103 If the snippet uses scheme, check that everything looks good and
 104 there are no security risks.
 105
 106 @warning{Somebody could sneak a @code{#'(system "rm -rf /")}
 107 command into our source tree if you do not do this!  Take this
 108 step @strong{VERY SERIOUSLY}.}
 109
 110 @end enumerate
 111
 112
 113 @node LSR to Git
 114 @section LSR to Git
 115
 116 @enumerate
 117
 118 @item
 119 Make sure that @command{convert-ly} and @command{lilypond} commands in
 120 current PATH are in a bleeding edge version -- latest release from
 121 master branch, or even better a fresh snapshot from Git master branch.
 122
 123 @item
 124 From the top source directory, run:
 125
 126 @example
 127 wget http://lsr.dsi.unimi.it/download/lsr-snippets-docs-@var{YYYY-MM-DD}.tar.gz
 128 tar -xzf lsr-snippets-docs-@var{YYYY-MM-DD}.tar.gz
 129 scripts/auxiliar/makelsr.py lsr-snippets-docs-@var{YYYY-MM-DD}
 130 @end example
 131
 132 @noindent
 133 where @var{YYYY-MM-DD} is the current date, e.g. 2009-02-28.
 134
 135 @item
 136 Follow the instructions printed on the console to manually check for
 137 unsafe files.
 138
 139 @warning{Somebody could sneak a @code{#'(system "rm -rf /")}
 140 command into our source tree if you do not do this!  Take this
 141 step @strong{VERY SERIOUSLY}.}
 142
 143 @item
 144 Do a git add / commit / push.
 145
 146 @end enumerate
 147
 148 Note that whenever there is one snippet from @file{input/new} and the
 149 other from LSR with the same file name, the one from @file{input/new}
 150 will be copied by @command{makelsr.py}.
 151
 152
 153 @node Fixing snippets in LilyPond sources
 154 @section Fixing snippets in LilyPond sources
 155
 156 In case some snippet from @file{input/lsr} cause the documentation
 157 compilation to fail, the following steps should be followed to fix it
 158 reliably.
 159
 160 @enumerate
 161
 162 @item
 163 Look up the snippet filename @file{@var{foo}.ly} in the error output
 164 or log, then fix the file @file{input/lsr/@var{foo}.ly} to make the
 165 documentation build succesfully.
 166
 167 @item
 168 Determine where it comes from by looking at its first line, e.g. run
 169
 170 @example
 171 head -1 input/lsr/@var{foo}.ly
 172 @end example
 173
 174 @item
 175 @strong{In case the snippet comes from LSR}, apply the fix to the
 176 snippet in LSR and send a notification email to a LSR editor with CC
 177 to the development list -- see @ref{Adding and editing snippets}.  The
 178 failure may sometimes not be caused by the snippet in LSR but by the
 179 syntax conversion made by @command{convert-ly}; in this case, try to
 180 fix @command{convert-ly} or report the problem on the development
 181 list, then run @command{makelsr.py} again, see @ref{LSR to Git}.  In
 182 some cases, when some features has been introduced or vastly changed
 183 so it requires (or takes significant advantage of) important changes
 184 in the snippet, it is simpler and recommended to write a new version
 185 of the snippet in @file{input/new}, then run @command{makelsr.py}.
 186
 187 @item
 188 @strong{In case the snippet comes from} @file{input/new}, apply in
 189 @file{input/new/@var{foo}.ly} the same fix you did in
 190 @file{input/lsr/@var{foo}.ly}.  In case the build failure was caused
 191 by a translation string, you may have to fix
 192 @file{input/texidocs/@var{foo}.texidoc} instead.
 193
 194 @item
 195 In any case, commit all changes to Git.
 196
 197 @end enumerate