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