Documentation/contributor/introduction.itexi

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