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 When you create (or find!) a nice snippet, please add it to LSR.  Go
  29 to @uref{http://lsr.dsi.unimi.it/, LSR} and log in (if you haven't
  30 already, create an account).  Follow the instructions on the website.
  31 These instructions also explain how to modify existing snippets.
  32
  33 If you think the snippet is particularly informative and you think
  34 it should be included in the documentation, tag it with @qq{docs}
  35 and one or more other categories.
  36
  37 Please make sure that the lilypond code follows the guidelines in
  38 @ref{LilyPond formatting}.
  39
  40
  41 @node Approving snippets
  42 @section Approving snippets
  43
  44 The main task of LSR editors is approving snippets.  To find a list of
  45 unapproved snippets, log into @uref{http://lsr.dsi.unimi.it/, LSR} and
  46 select @qq{No} from the dropdown menu to the right of the word
  47 @qq{Approved} at the bottom of the interface, then click
  48 @qq{Enable filter}.
  49
  50 Check each snippet:
  51
  52 @enumerate
  53
  54 @item
  55 Does the snippet make sense and does what the author claims that
  56 it does?  If you think the snippet is particularly helpful, add
  57 the @qq{docs} tag and at least one other tag.
  58
  59 @item
  60 If the snippet is tagged with @qq{docs}, check to see if it
  61 matches our guidelines for @ref{LilyPond formatting}.
  62
  63 @item
  64 If the snippet uses scheme, check that everything looks good and
  65 there are no security risks.
  66
  67 @warning{Somebody could sneak a @code{#'(system "rm -rf /")}
  68 command into our source tree if you do not do this!  Take this
  69 step @strong{VERY SERIOUSLY}.}
  70
  71 @end enumerate
  72
  73
  74 @node LSR to Git
  75 @section LSR to Git
  76
  77 @enumerate
  78
  79 @item
  80 Make sure that @command{convert-ly} and @command{lilypond} commands in
  81 current PATH are in a bleeding edge version -- latest release from
  82 master branch, or even better a fresh snapshot from Git master branch.
  83
  84 @item
  85 From the top source directory, run:
  86
  87 @example
  88 wget http://lsr.dsi.unimi.it/download/lsr-snippets-docs-@var{YYYY-MM-DD}.tar.gz
  89 tar -xzf lsr-snippets-docs-@var{YYYY-MM-DD}.tar.gz
  90 scripts/auxiliar/makelsr.py lsr-snippets-docs-@var{YYYY-MM-DD}
  91 @end example
  92
  93 @noindent
  94 where @var{YYYY-MM-DD} is the current date, e.g. 2009-02-28.
  95
  96 @item
  97 Follow the instructions printed on the console to manually check for
  98 unsafe files.
  99
 100 @warning{Somebody could sneak a @code{#'(system "rm -rf /")}
 101 command into our source tree if you do not do this!  Take this
 102 step @strong{VERY SERIOUSLY}.}
 103
 104 @item
 105 Do a git add / commit / push.
 106
 107 @end enumerate
 108
 109
 110 @node Fixing snippets in LilyPond sources
 111 @section Fixing snippets in LilyPond sources
 112
 113 In case some snippet from @file{input/lsr} cause the documentation
 114 compilation to fail, the following steps should be followed to fix it
 115 reliably.
 116
 117 @enumerate
 118
 119 @item
 120 Look up the snippet filename @file{@var{foo}.ly} in the error output
 121 or log, then fix the file @file{input/lsr/@var{foo}.ly} to make the
 122 documentation build succesfully.
 123
 124 @item
 125 Determine where it comes from by looking at its first line, e.g. run
 126
 127 @example
 128 head -1 input/lsr/@var{foo}.ly
 129 @end example
 130
 131 @item
 132 @strong{In case the snippet comes from LSR}, apply the fix to the
 133 snippet in LSR and send a notification email to a LSR editor with CC
 134 to the development list -- see @ref{Adding and editing snippets}.  The
 135 failure may sometimes not be caused by the snippet in LSR but by the
 136 syntax conversion made by @command{convert-ly}; in this case, try to
 137 fix @command{convert-ly} or report the problem on the development
 138 list, then run @command{makelsr.py} again, see @ref{LSR to Git}.  In
 139 some cases, when some features has been introduced or vastly changed
 140 so it requires (or takes significant advantage of) important changes
 141 in the snippet, it is simpler and recommended to write a new version
 142 of the snippet in @file{input/new}, then run @command{makelsr.py}.
 143
 144 @item
 145 @strong{In case the snippet comes from} @file{input/new}, apply in
 146 @file{input/new/@var{foo}.ly} the same fix you did in
 147 @file{input/lsr/@var{foo}.ly}.  In case the build failure was caused
 148 by a translation string, you may have to fix
 149 @file{input/texidocs/@var{foo}.texidoc} instead.
 150
 151 @item
 152 In any case, commit all changes to Git.
 153
 154 @end enumerate