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 * Mentors::
  15 @end menu
  16
  17
  18 @node Help us
  19 @section Help us
  20
  21 @helpusNeed
  22
  23 @helpusTasks
  24
  25 @helpusProjects
  26
  27
  28 @node Overview of work flow
  29 @section Overview of work flow
  30
  31 @cartouche
  32 @strong{Short summary for Unix developers}: source code is at
  33 @uref{git://git.sv.gnu.org/lilypond.git}.  Documentation is built
  34 with Texinfo, after pre-processing with @code{lilypond-book}.
  35 Send well-formed patches to @email{lilypond-devel@@gnu.org}.
  36 @end cartouche
  37
  38 Git is a @emph{version control system} that tracks the history of
  39 a program's source code.  The LilyPond source code is maintained
  40 as a Git repository, which contains:
  41
  42 @itemize
  43 @item
  44 all of the source files needed to build LilyPond, and
  45
  46 @item
  47 a record of the entire history of every change made to every file
  48 since the program was born.
  49 @end itemize
  50
  51 The @q{official} LilyPond Git repository is hosted by the GNU
  52 Savannah software forge at @uref{http://git.sv.gnu.org}.
  53 Although, since Git uses a @emph{distributed} model, technically
  54 there is no central repository.  Instead, each contributor keeps a
  55 complete copy of the entire repository (about 116MB).
  56
  57 Changes made within one contributor's copy of the repository can
  58 be shared with other contributors using @emph{patches}.  A patch
  59 is a simple text file generated by the @command{git} program that
  60 indicates what changes have been made (using a special format).
  61 If a contributor's patch is approved for inclusion (usually
  62 through the mailing list), someone on the current development team
  63 will @emph{push} the patch to the official repository.
  64
  65 The Savannah software forge provides two separate interfaces for
  66 viewing the LilyPond Git repository online: @emph{cgit} and
  67 @emph{gitweb}.  The cgit interface should work faster than gitweb
  68 in most situations, but only gitweb allows you to search through
  69 the source code using @command{grep}, which you may find useful.
  70 The cgit interface is at
  71 @uref{http://git.sv.gnu.org/cgit/lilypond.git/} and the gitweb
  72 interface is at
  73 @uref{http://git.sv.gnu.org/gitweb/?p=lilypond.git}.
  74
  75 Git is a complex and powerful tool, but tends to be confusing at
  76 first, particularly for users not familiar with the command line
  77 and/or version control systems.  We have created the
  78 @command{lily-git} graphical user interface to ease this
  79 difficulty.
  80
  81 @emph{Compiling} (@q{building}) LilyPond allows developers to see
  82 how changes to the source code affect the program itself.
  83 Compiling is also needed to package the program for specific
  84 operating systems or distributions.  LilyPond can be compiled from
  85 a local Git repository (for developers), or from a downloaded
  86 tarball (for packagers).  Compiling LilyPond is a rather involved
  87 process, and most contributor tasks do not require it.
  88
  89 Contributors can contact the developers through the
  90 @q{lilypond-devel} mailing list.  The mailing list archive is
  91 located at
  92 @uref{http://lists.gnu.org/archive/html/lilypond-devel/}.  If you
  93 have a question for the developers, search the archives first to
  94 see if the issue has already been discussed.  Otherwise, send an
  95 email to @email{lilypond-devel@@gnu.org}.  You can subscribe to
  96 the developers' mailing list here:
  97 @uref{http://lists.gnu.org/mailman/listinfo/lilypond-devel}.
  98
  99 @warning{Contributors on Windows or MacOS X wishing to compile
 100 code or documentation are strongly advised to use our Ubuntu
 101 LilyPond Developer Remix, as discussed in @ref{Quick start}.}
 102
 103
 104 @node Mentors
 105 @section Mentors
 106
 107 We have a semi-formal system of mentorship, similar to the
 108 medieval @qq{journeyman/master} training system.  New contributors
 109 will have a dedicated mentor to help them @qq{learn the ropes}.
 110
 111 @warning{This is subject to the availability of mentors; certain
 112 jobs have more potential mentors than others.}
 113
 114 @subheading Contributor responsibilities
 115
 116 @enumerate
 117
 118 @item
 119 Ask your mentor which sections of the CG you should read.
 120
 121 @item
 122 If you get stuck for longer than 10 minutes, ask your mentor.
 123 They might not be able to help you with all problems, but we find
 124 that new contributors often get stuck with something that could be
 125 solved/explained with 2 or 3 sentences from a mentor.
 126
 127 @item
 128 If you have been working on a task much longer than was originally
 129 estimated, stop and ask your mentor.  There may have been a
 130 miscommunication, or there may be some time-saving tips that could
 131 vastly simply your task.
 132
 133 @item
 134 Send patches to your mentor for initial comments.
 135
 136 @item
 137 Inform your mentor if you're going to be away for a month, or if
 138 you leave entirely.  Contributing to lilypond isn't for everybody;
 139 just let your mentor know so that we can reassign that work to
 140 somebody else.
 141
 142 @item
 143 Inform your mentor if you're willing to do more work -- we always
 144 have way more work than we have helpers available.  We try to
 145 avoid overwhelming new contributors, so you'll be given less work
 146 than we think you can handle.
 147
 148 @end enumerate
 149
 150
 151 @subheading Mentor responsibilities
 152
 153 @enumerate
 154
 155 @item
 156 Respond to questions from your contributor(s) promptly, even if
 157 the response is just @qq{sorry, I don't know} or @qq{sorry, I'm
 158 very busy for the next 3 days; I'll get back to you then}.  Make
 159 sure they feel valued.
 160
 161 @item
 162 Inform your contributor(s) about the expected turnaround for your
 163 emails -- do you work on lilypond every day, or every weekend, or
 164 what?  Also, if you'll be unavailable for longer than usual (say,
 165 if you normally reply within 24 hours, but you'll be at a
 166 conference for a week), let your contributors know.  Again, make
 167 sure they feel valued, and that your silence (if they ask a
 168 question during that period) isn't their fault.
 169
 170 @item
 171 Inform your contributor(s) if they need to do anything unusual for
 172 the builds, such as doing a @qq{make clean / doc-clean} or
 173 switching git branches (not expected, but just in case...)
 174
 175 @item
 176 You don't need to be able to completely approve patches.  Make
 177 sure the patch meets whatever you know of the guidelines (for doc
 178 style, code indentation, whatever), and then send it on to the
 179 frog list or -devel for more comments.  If you feel confident
 180 about the patch, you can push it directly (this is mainly intended
 181 for docs and translations; code patches should almost always go to
 182 -devel before being pushed).
 183
 184 @item
 185 Keep track of patches from your contributor.  Either upload them
 186 to Rietveld yourself, or help+encourage them to upload the patches
 187 themselves.  When a patch is on Rietveld, it's your responbility
 188 to get comments for it, and to add a link to the patch to the
 189 google tracker.  (tag it @qq{patch-new}, or @qq{patch-review} if
 190 you feel very confident in it)
 191
 192 @item
 193 Encourage your contributor to review patches, particularly your
 194 own!  It doesn't matter if they're not familiar with C++ / scheme
 195 / build system / doc stuff -- simply going through the process is
 196 valuable.  Besides, anybody can find a typo!
 197
 198 @item
 199 Contact your contributor at least once a week.  The goal is just
 200 to get a conversation started -- there's nothing wrong with simply
 201 copy&pasting this into an email:
 202
 203 @example
 204 Hey there,
 205
 206 How are things going?  If you sent a patch and got a review, do
 207 you know what you need to fix?  If you sent a patch but have no
 208 reviews yet, do you know when you will get reviews?  If you are
 209 working on a patch, what step(s) are you working on?
 210 @end example
 211
 212
 213 @end enumerate
 214
 215