Documentation/contributor/introduction.itexi

   1 @c -*- coding: utf-8; mode: texinfo; -*-
   2
   3 @include included/helpus.itexi
   4
   5 @node Introduction to contributing
   6 @chapter Introduction to contributing
   7
   8 This chapter presents a quick overview of ways that people can
   9 help LilyPond.
  10
  11 @menu
  12 * Help us::
  13 * Overview of work flow::
  14 * Summary for experienced developers::
  15 * Mentors::
  16 @end menu
  17
  18
  19 @node Help us
  20 @section Help us
  21
  22 @helpusNeed
  23
  24 @helpusSimple
  25
  26 @helpusAdvanced
  27
  28
  29 @node Overview of work flow
  30 @section Overview of work flow
  31
  32 @advanced{Experienced developers should skip to
  33 @ref{Summary for experienced developers}.}
  34
  35 Git is a @emph{version control system} that tracks the history of
  36 a program's source code.  The LilyPond source code is maintained
  37 as a Git repository, which contains:
  38
  39 @itemize
  40 @item
  41 all of the source files needed to build LilyPond, and
  42
  43 @item
  44 a record of the entire history of every change made to every file
  45 since the program was born.
  46 @end itemize
  47
  48 The @q{official} LilyPond Git repository is hosted by the GNU
  49 Savannah software forge at @uref{http://git.sv.gnu.org}.
  50
  51 Changes made within one contributor's copy of the repository can
  52 be shared with other contributors using @emph{patches}.  A patch
  53 is a text file that indicates what changes have been made.
  54 If a contributor's patch is approved for inclusion (usually
  55 through the mailing list), someone on the current development team
  56 will @emph{push} the patch to the official repository.
  57
  58 The Savannah software forge provides two separate interfaces for
  59 viewing the LilyPond Git repository online:
  60 @uref{http://git.sv.gnu.org/cgit/lilypond.git/, cgit} and
  61 @uref{http://git.sv.gnu.org/gitweb/?p=lilypond.git, gitweb}.
  62
  63 @ignore
  64 The cgit interface should work faster than gitweb
  65 in most situations, but only gitweb allows you to search through
  66 the source code using @command{grep}, which you may find useful.
  67 @end ignore
  68
  69 Git is a complex and powerful tool, but tends to be confusing at
  70 first, particularly for users not familiar with the command line
  71 and/or version control systems.  We have created the
  72 @command{lily-git} graphical user interface to ease this
  73 difficulty.
  74
  75 @emph{Compiling} (@q{building}) LilyPond allows developers to see
  76 how changes to the source code affect the program itself.
  77 Compiling is also needed to package the program for specific
  78 operating systems or distributions.  LilyPond can be compiled from
  79 a local Git repository (for developers), or from a downloaded
  80 tarball (for packagers).  Compiling LilyPond is a rather involved
  81 process, and most contributor tasks do not require it.
  82
  83 Contributors can contact the developers through the
  84 @q{lilypond-devel} mailing list.  The mailing list archive is
  85 located at
  86 @uref{http://lists.gnu.org/archive/html/lilypond-devel/}.  If you
  87 have a question for the developers, search the archives first to
  88 see if the issue has already been discussed.  Otherwise, send an
  89 email to @email{lilypond-devel@@gnu.org}.  You can subscribe to
  90 the developers' mailing list here:
  91 @uref{http://lists.gnu.org/mailman/listinfo/lilypond-devel}.
  92
  93 @warning{Contributors on Windows or MacOS X wishing to compile
  94 code or documentation are strongly advised to use our Debian
  95 LilyPond Developer Remix, as discussed in @ref{Quick start}.}
  96
  97
  98 @node Summary for experienced developers
  99 @section Summary for experienced developers
 100
 101 If you are already familiar with typical open-source tools, here's
 102 what you need to know:
 103
 104 @itemize
 105 @item @strong{source repository}:
 106 hosted by GNU savannah.
 107
 108 @example
 109 @uref{http://git.savannah.gnu.org/gitweb/?p=lilypond.git}
 110 @end example
 111
 112 @item @strong{environment variables}:
 113 many maintenance scripts, and many instructions in this guide rely on
 114 predefined @ref{Environment variables}.
 115
 116 @item @strong{mailing lists}:
 117 given on @rweb{Contact}.
 118
 119 @item @strong{branches}:
 120
 121 @itemize
 122 @item @code{master}:
 123 base your work from this, but do @strong{not push} to it.
 124
 125 @item @code{staging}:
 126 after a successful review (see below), push here.
 127
 128 @item @code{translation}:
 129 translators should base their work from this, and also push to it.
 130
 131 @item @code{dev/foo}:
 132 feel free to push any new branch name under @code{dev/}.
 133
 134 @end itemize
 135
 136 @item @strong{regression tests}:
 137 also known as @qq{regtests}; this is a collection of more than a
 138 thousand .ly files.  We track the output of those files between
 139 versions.
 140
 141 If a patch introduces any unintentional changes to the regtests,
 142 we will likely reject it -- make sure that you are aware and can
 143 explain any regtest changes.  More info in @ref{Regression tests}.
 144
 145 @item @strong{reviews}:
 146 after finishing work on a patch or branch:
 147
 148 @enumerate
 149 @item
 150 upload it with our custom @code{git-cl} @q{helper-script}; see
 151 @ref{git-cl}.  In addition to uploading patches to the Google's Rietveld
 152 Code Review Tool the script will also update the issue tracker (or add a
 153 new issue as appropriate) so that we don't lose reference to your
 154 patch.  The @qq{status} of your patch is kept on the issue tracker;
 155 see @ref{Issues}.
 156
 157 Your patch will be given @code{Patch-new} status.  More information on
 158 this can be found in the section @ref{Uploading a patch for review}.
 159
 160 @item
 161 If your patch passes some automatic tests, it will be given
 162 @code{Patch-review} status.  This generally happens within 24
 163 hours.
 164
 165 @item
 166 After that, the patch must wait for the next @qq{patch countdown},
 167 which occurs roughly every 3 days.  When your patch is put on a
 168 countdown, it will be given @code{Patch-countdown} status.
 169
 170 @item
 171 The countdown is a 72-hour period which gives other developers one
 172 last chance to review the patch.  If no significant problems are
 173 found, your patch will be given @code{Patch-push} status.
 174
 175 @item
 176 You may now either push it to the @code{staging} branch, or email
 177 your patch (created with @w{@code{git format-patch}}) to somebody
 178 who will push it for you.
 179
 180 @end enumerate
 181
 182 @advanced{Yes, this process means that most patches wait between
 183 60-120 hours before reaching @code{master}.  This is unfortunate, but
 184 given our limited resources for reviewing patches and a history of
 185 unintended breakage in @code{master}, this is the best compromise
 186 we have found.}
 187
 188 @end itemize
 189
 190
 191 @node Mentors
 192 @section Mentors
 193
 194 We have a semi-formal system of mentorship, similar to the
 195 medieval @qq{journeyman/master} training system.  New contributors
 196 will have a dedicated mentor to help them @qq{learn the ropes}.
 197
 198 @warning{This is subject to the availability of mentors; certain
 199 jobs have more potential mentors than others.}
 200
 201 @subheading Contributor responsibilities
 202
 203 @enumerate
 204
 205 @item
 206 Ask your mentor which sections of the CG you should read.
 207
 208 @item
 209 If you get stuck for longer than 10 minutes, ask your mentor.
 210 They might not be able to help you with all problems, but we find
 211 that new contributors often get stuck with something that could be
 212 solved/explained with 2 or 3 sentences from a mentor.
 213
 214 @item
 215 If you have been working on a task much longer than was originally
 216 estimated, stop and ask your mentor.  There may have been a
 217 miscommunication, or there may be some time-saving tips that could
 218 vastly simply your task.
 219
 220 @item
 221 Send patches to your mentor for initial comments.
 222
 223 @item
 224 Inform your mentor if you're going to be away for a month, or if
 225 you leave entirely.  Contributing to lilypond isn't for everybody;
 226 just let your mentor know so that we can reassign that work to
 227 somebody else.
 228
 229 @item
 230 Inform your mentor if you're willing to do more work -- we always
 231 have way more work than we have helpers available.  We try to
 232 avoid overwhelming new contributors, so you'll be given less work
 233 than we think you can handle.
 234
 235 @end enumerate
 236
 237
 238 @subheading Mentor responsibilities
 239
 240 @enumerate
 241
 242 @item
 243 Respond to questions from your contributor(s) promptly, even if
 244 the response is just @qq{sorry, I don't know} or @qq{sorry, I'm
 245 very busy for the next 3 days; I'll get back to you then}.  Make
 246 sure they feel valued.
 247
 248 @item
 249 Inform your contributor(s) about the expected turnaround for your
 250 emails -- do you work on lilypond every day, or every weekend, or
 251 what?  Also, if you'll be unavailable for longer than usual (say,
 252 if you normally reply within 24 hours, but you'll be at a
 253 conference for a week), let your contributors know.  Again, make
 254 sure they feel valued, and that your silence (if they ask a
 255 question during that period) isn't their fault.
 256
 257 @item
 258 Inform your contributor(s) if they need to do anything unusual for
 259 the builds, such as doing a @qq{make clean / doc-clean} or
 260 switching git branches (not expected, but just in case...)
 261
 262 @item
 263 You don't need to be able to completely approve patches.  Make
 264 sure the patch meets whatever you know of the guidelines (for doc
 265 style, code indentation, whatever), and then send it on to -devel
 266 for more comments.  If you feel confident
 267 about the patch, you can push it directly (this is mainly intended
 268 for docs and translations; code patches should almost always go to
 269 -devel before being pushed).
 270
 271 @item
 272 Keep track of patches from your contributor.  Either upload them
 273 to Rietveld yourself, or help+encourage them to upload the patches
 274 themselves.  When a patch is on Rietveld, it's your responbility
 275 to get comments for it, and to add a link to the patch to the
 276 google tracker.  (tag it @qq{patch-new}, or @qq{patch-review} if
 277 you feel very confident in it)
 278
 279 @item
 280 Encourage your contributor to review patches, particularly your
 281 own!  It doesn't matter if they're not familiar with C++ / scheme
 282 / build system / doc stuff -- simply going through the process is
 283 valuable.  Besides, anybody can find a typo!
 284
 285 @item
 286 Contact your contributor at least once a week.  The goal is just
 287 to get a conversation started -- there's nothing wrong with simply
 288 copy&pasting this into an email:
 289
 290 @example
 291 Hey there,
 292
 293 How are things going?  If you sent a patch and got a review, do
 294 you know what you need to fix?  If you sent a patch but have no
 295 reviews yet, do you know when you will get reviews?  If you are
 296 working on a patch, what step(s) are you working on?
 297 @end example
 298
 299
 300 @end enumerate
 301
 302