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