Documentation/contributor/introduction.itexi

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