Documentation/contributor/introduction.itexi

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