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}.  In addition to uploading
 151 it to the google rietveld code review tool, this adds a tracker
 152 issue so that we don't lose your patch.  The @qq{status} of your
 153 patch is kept on the issue tracker; see @ref{Issues}.
 154
 155 @example
 156 @uref{https://github.com/gperciva/git-cl}
 157 @end example
 158
 159 Your patch will be given @code{Patch-new} status.  More info in
 160 @ref{Uploading a patch for review}.
 161
 162 @item
 163 If your patch passes some automatic tests, it will be given
 164 @code{Patch-review} status.  This generally happens within 24
 165 hours.
 166
 167 @item
 168 After that, the patch must wait for the next @qq{patch countdown},
 169 which occur 3 times a week.  If there are a lot of patches waiting
 170 for a countdown, a subset of patches are chosen randomly.  When
 171 your patch is put on a countdown, it will be given
 172 @code{Patch-countdown} status.
 173
 174 @item
 175 The countdown is a 48-hour period which gives other developers one
 176 last chance to review the patch.  If no significant problems are
 177 found, your patch will be given @code{Patch-push} status.
 178
 179 @item
 180 You may now either push it to the @code{staging} branch, or email
 181 your patch (created with @w{@code{git format-patch}}) to somebody
 182 who will push it for you.
 183
 184 @end enumerate
 185
 186 @advanced{Yes, this process means that most patches wait between
 187 60-120 hours before reaching @code{master}.  This is unfortunate, but
 188 given our limited resources for reviewing patches and a history of
 189 unintended breakage in @code{master}, this is the best compromise
 190 we have found.}
 191
 192 @c I don't think this is important enough to list here, but I may
 193 @c change my mind and/or leave a link to a later CG section.
 194 @ignore
 195 @item @strong{code style}:
 196 C++ code should be formatted with
 197 @file{scripts/auxiliar/fixcc.py}, which requires
 198 @url{http://astyle.sourceforge.net/, astyle 2.02}.  However, we
 199 are not very strict about this requirement.
 200
 201 At the moment, scheme code should be formatted @qq{like emacs does
 202 it}.  We are working on an automated tool to simplify this step.
 203 However, we are not very strict about this requirement either.
 204 @end ignore
 205
 206 @end itemize
 207
 208
 209 @node Mentors
 210 @section Mentors
 211
 212 We have a semi-formal system of mentorship, similar to the
 213 medieval @qq{journeyman/master} training system.  New contributors
 214 will have a dedicated mentor to help them @qq{learn the ropes}.
 215
 216 @warning{This is subject to the availability of mentors; certain
 217 jobs have more potential mentors than others.}
 218
 219 @subheading Contributor responsibilities
 220
 221 @enumerate
 222
 223 @item
 224 Ask your mentor which sections of the CG you should read.
 225
 226 @item
 227 If you get stuck for longer than 10 minutes, ask your mentor.
 228 They might not be able to help you with all problems, but we find
 229 that new contributors often get stuck with something that could be
 230 solved/explained with 2 or 3 sentences from a mentor.
 231
 232 @item
 233 If you have been working on a task much longer than was originally
 234 estimated, stop and ask your mentor.  There may have been a
 235 miscommunication, or there may be some time-saving tips that could
 236 vastly simply your task.
 237
 238 @item
 239 Send patches to your mentor for initial comments.
 240
 241 @item
 242 Inform your mentor if you're going to be away for a month, or if
 243 you leave entirely.  Contributing to lilypond isn't for everybody;
 244 just let your mentor know so that we can reassign that work to
 245 somebody else.
 246
 247 @item
 248 Inform your mentor if you're willing to do more work -- we always
 249 have way more work than we have helpers available.  We try to
 250 avoid overwhelming new contributors, so you'll be given less work
 251 than we think you can handle.
 252
 253 @end enumerate
 254
 255
 256 @subheading Mentor responsibilities
 257
 258 @enumerate
 259
 260 @item
 261 Respond to questions from your contributor(s) promptly, even if
 262 the response is just @qq{sorry, I don't know} or @qq{sorry, I'm
 263 very busy for the next 3 days; I'll get back to you then}.  Make
 264 sure they feel valued.
 265
 266 @item
 267 Inform your contributor(s) about the expected turnaround for your
 268 emails -- do you work on lilypond every day, or every weekend, or
 269 what?  Also, if you'll be unavailable for longer than usual (say,
 270 if you normally reply within 24 hours, but you'll be at a
 271 conference for a week), let your contributors know.  Again, make
 272 sure they feel valued, and that your silence (if they ask a
 273 question during that period) isn't their fault.
 274
 275 @item
 276 Inform your contributor(s) if they need to do anything unusual for
 277 the builds, such as doing a @qq{make clean / doc-clean} or
 278 switching git branches (not expected, but just in case...)
 279
 280 @item
 281 You don't need to be able to completely approve patches.  Make
 282 sure the patch meets whatever you know of the guidelines (for doc
 283 style, code indentation, whatever), and then send it on to -devel
 284 for more comments.  If you feel confident
 285 about the patch, you can push it directly (this is mainly intended
 286 for docs and translations; code patches should almost always go to
 287 -devel before being pushed).
 288
 289 @item
 290 Keep track of patches from your contributor.  Either upload them
 291 to Rietveld yourself, or help+encourage them to upload the patches
 292 themselves.  When a patch is on Rietveld, it's your responbility
 293 to get comments for it, and to add a link to the patch to the
 294 google tracker.  (tag it @qq{patch-new}, or @qq{patch-review} if
 295 you feel very confident in it)
 296
 297 @item
 298 Encourage your contributor to review patches, particularly your
 299 own!  It doesn't matter if they're not familiar with C++ / scheme
 300 / build system / doc stuff -- simply going through the process is
 301 valuable.  Besides, anybody can find a typo!
 302
 303 @item
 304 Contact your contributor at least once a week.  The goal is just
 305 to get a conversation started -- there's nothing wrong with simply
 306 copy&pasting this into an email:
 307
 308 @example
 309 Hey there,
 310
 311 How are things going?  If you sent a patch and got a review, do
 312 you know what you need to fix?  If you sent a patch but have no
 313 reviews yet, do you know when you will get reviews?  If you are
 314 working on a patch, what step(s) are you working on?
 315 @end example
 316
 317
 318 @end enumerate
 319
 320