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 * Lilybuntu::
  15 * Mentors::
  16 @end menu
  17
  18
  19 @node Help us
  20 @section Help us
  21
  22 @helpusNeed
  23
  24 @helpusTasks
  25
  26 @helpusProjects
  27
  28
  29 @node Overview of work flow
  30 @section Overview of work flow
  31
  32 @cartouche
  33 @strong{Ultra-short summary for Unix developers}: source code is at
  34 @code{git://git.sv.gnu.org/lilypond.git}.  Documentation is built
  35 with Texinfo, after pre-processing with @code{lilypond-book}.
  36 Send well-formed patches to @email{lilypond-devel@@gnu.org}.
  37 @end cartouche
  38
  39 Git is a @emph{version control system} that tracks the history of
  40 a program's source code.  The LilyPond source code is maintained
  41 as a Git repository, which contains:
  42
  43 @itemize
  44 @item
  45 all of the source files needed to build LilyPond, and
  46
  47 @item
  48 a record of the entire history of every change made to every file
  49 since the program was born.
  50 @end itemize
  51
  52 The @q{official} LilyPond Git repository is hosted by the GNU
  53 Savannah software forge at @uref{http://git.sv.gnu.org}.
  54 Although, since Git uses a @emph{distributed} model, technically
  55 there is no central repository.  Instead, each contributor keeps a
  56 complete copy of the entire repository (about 116M).
  57
  58 Changes made within one contributor's copy of the repository can
  59 be shared with other contributors using @emph{patches}.  A patch
  60 is a simple text file generated by the @command{git} program that
  61 indicates what changes have been made (using a special format).
  62 If a contributor's patch is approved for inclusion (usually
  63 through the mailing list), someone on the current development team
  64 will @emph{push} the patch to the official repository.
  65
  66 The Savannah software forge provides two separate interfaces for
  67 viewing the LilyPond Git repository online: @emph{cgit} and
  68 @emph{gitweb}.  The cgit interface should work faster than gitweb
  69 in most situations, but only gitweb allows you to search through
  70 the source code using @command{grep}, which you may find useful.
  71 The cgit interface is at
  72 @uref{http://git.sv.gnu.org/cgit/lilypond.git/} and the gitweb
  73 interface is at
  74 @uref{http://git.sv.gnu.org/gitweb/?p=lilypond.git}.
  75
  76 Git is a complex and powerful tool, but tends to be confusing at
  77 first, particularly for users not familiar with the command line
  78 and/or version control systems.  Contributors who don't want to
  79 deal with Git directly are encouraged to use the
  80 @command{lily-git} graphical user interface instead.
  81
  82 @emph{Compiling} (@q{building}) LilyPond allows developers to see
  83 how changes to the source code affect the program itself.
  84 Compiling is also needed to package the program for specific
  85 operating systems or distributions.  LilyPond can be compiled from
  86 a local Git repository (for developers), or from a downloaded
  87 tarball (for packagers).  Compiling LilyPond is a rather involved
  88 process, and most contributor tasks do not require it.
  89
  90 Contributors can contact the developers through the
  91 @q{lilypond-devel} mailing list.  The mailing list archive is
  92 located at
  93 @uref{http://lists.gnu.org/archive/html/lilypond-devel/}.  If you
  94 have a question for the developers, search the archives first to
  95 see if the issue has already been discussed.  Otherwise, send an
  96 email to @email{lilypond-devel@@gnu.org}.  You can subscribe to
  97 the developers' mailing list here:
  98 @uref{http://lists.gnu.org/mailman/listinfo/lilypond-devel}.
  99
 100 @warning{Contributors on Windows or MacOS X wishing to compile
 101 code or documentation are strongly advised to use @ref{Lilybuntu}
 102 instead of trying to install all software dependencies
 103 themselves.}
 104
 105
 106 @node Lilybuntu
 107 @section Lilybuntu
 108
 109 It is not possible to compile LilyPond on Windows, and extremely
 110 difficulty to compile it on MacOS X.  We have therefore made a
 111 @q{remix} of Ubuntu which includes all necessary dependencies to
 112 compile both LilyPond and the documentation.  This can be run
 113 inside a virtual machine without disturbing your main operating
 114 system.
 115
 116 @enumerate
 117 @item
 118 Install some virtualization software.
 119
 120 Any virtualization tool can be used, but we recommend VirtualBox:
 121
 122 @example
 123 @uref{http://@/www.virtualbox.org/@/wiki/@/Downloads}
 124 @end example
 125
 126 In virtualization terminology, your main operating system is the
 127 @qq{host}.
 128
 129 @item
 130 Download the @file{lilybuntu2.iso} disk image:
 131
 132 @example
 133 @uref{http://files.lilynet.net/lilybuntu2.iso}
 134 @end example
 135
 136 @advanced{There is a md5sum available:
 137 @uref{http://files.lilynet.net/lilybuntu2.iso.md5}}
 138
 139 @item
 140 Install @file{lilybuntu2.iso} as the @qq{guest} operating system
 141 on your virtualized system.
 142
 143 @itemize
 144
 145 @item
 146 If possible, use at least 700 MB of RAM (1GB would be better) for
 147 the virtual machine, and use @qq{dynamically expanding storage}
 148 for the virtual hard drive.  A complete compile of everything
 149 (code, docs, regression tests) can reach 10 GB.
 150
 151 @item
 152 When @file{lilybuntu2.iso} boots, it shows an ISOLINUX
 153 @code{boot:} prompt.  Type:
 154
 155 @example
 156 install
 157 @end example
 158
 159 @item
 160 At the @qq{Prepare disk space} stage, do not be afraid to select
 161 @qq{Erase and use the entire disk}, since this refers to your
 162 @emph{virtual disk}, not your machine's actual hard drive.
 163
 164 @item
 165 After restarting your system, if you see the ISOLINUX @code{boot:}
 166 prompt again, go to
 167 @w{Devices@arrow{}CD/DVD Devices@arrow{}} and @emph{de-select}
 168 the @q{lilybuntu2.iso} option, then reboot.
 169
 170 @end itemize
 171
 172 @advanced{
 173 The latest version of lilybuntu is based on Ubuntu 10.04.1; if you
 174 encounter any difficulties installing it, search for one of the
 175 many tutorials for installing that particular version of Ubuntu as
 176 a client operating system.
 177 }
 178
 179 @item
 180 Do any extra configuration for your virtualization software.
 181
 182 VirtualBox has extra @qq{guest additions} which can make the
 183 virtualization easier to use (full-screen, easy file sharing
 184 between host and client operating systems, shared clipboards,
 185 etc).
 186
 187 @enumerate
 188
 189 @item
 190 From the @code{Devices} menu of VirtualBox, select @code{Install
 191 Guest Additions...}.
 192
 193 @item
 194 From the @code{Places} menu of Ubuntu, select
 195 @code{VBOXADDITIONS_}.  A file-system window will open.
 196
 197 @item
 198 Double-click on the @file{autorun.sh} file, then select @qq{Run in
 199 Terminal}, and enter your password when prompted.
 200
 201 @item
 202 Once the script is finished, reboot your Virtual Machine to
 203 complete the installation.
 204
 205 @advanced{If you do any kernel upgrades, you may need to re-run
 206 these VBOXADDITIONS instructions.}
 207
 208 @end enumerate
 209
 210 If you use other virutalization software, then follow the normal
 211 procedures for your virtualization software with Ubuntu as the
 212 client.
 213
 214 @end enumerate
 215
 216 Follow instructions for Linux when reading instructions about
 217 @ref{Working with source code}, or @ref{Compiling}.
 218
 219 If you are not familiar with Linux, it may be benefitial to read a
 220 couple of @qq{introduction to Ubuntu} webpages.  One particular
 221 change from Windows and MacOS X is that most software should be
 222 installed with your @qq{package manager}; this vastly simplifies
 223 the process of installing and configuring software.  Go to
 224 @w{System@arrow{}Administration@arrow{}Synaptic Package Manager}.
 225
 226
 227 @advanced{not all hardware is supported in all virtualization
 228 tools.  In particular, some contributors have reported problems
 229 with USB devices.  If you would like to investigate further, then
 230 look for help for your virtualization tool using your normal OS as
 231 the @qq{host} and Ubuntu as the @qq{client}.
 232 }
 233
 234
 235 @node Mentors
 236 @section Mentors
 237
 238 We have a semi-formal system of mentorship, similar to the
 239 medieval @qq{journeyman/master} training system.  New contributors
 240 will have a dedicated mentor to help them @qq{learn the ropes}.
 241
 242 @warning{This is subject to the availability of mentors; certain
 243 jobs have more potential mentors than others.}
 244
 245 @subheading Contributor responsibilities
 246
 247 @enumerate
 248
 249 @item
 250 Ask your mentor which sections of the CG you should read.
 251
 252 @item
 253 If you get stuck for longer than 10 minutes, ask your mentor.
 254 They might not be able to help you with all problems, but we find
 255 that new contributors often get stuck with something that could be
 256 solved/explained with 2 or 3 sentences from a mentor.
 257
 258 @item
 259 Send patches to your mentor for initial comments.
 260
 261 @item
 262 Inform your mentor if you're going to be away for a month, or if
 263 you leave entirely.  Contributing to lilypond isn't for everybody;
 264 just let your mentor know so that we can reassign that work to
 265 somebody else.
 266
 267 @item
 268 Inform your mentor if you're willing to do more work -- we always
 269 have way more work than we have helpers available.  We try to
 270 avoid overwhelming new contributors, so you'll be given less work
 271 than we think you can handle.
 272
 273 @end enumerate
 274
 275
 276 @subheading Mentor responsibilities
 277
 278 @enumerate
 279
 280 @item
 281 Respond to questions from your contributor(s) promptly, even if
 282 the response is just @qq{sorry, I don't know} or @qq{sorry, I'm
 283 very busy for the next 3 days; I'll get back to you then}.  Make
 284 sure they feel valued.
 285
 286 @item
 287 Inform your contributor(s) about the expected turnaround for your
 288 emails -- do you work on lilypond every day, or every weekend, or
 289 what?  Also, if you'll be unavailable for longer than usual (say,
 290 if you normally reply within 24 hours, but you'll be at a
 291 conference for a week), let your contributors know.  Again, make
 292 sure they feel valued, and that your silence (if they ask a
 293 question during that period) isn't their fault.
 294
 295 @item
 296 Inform your contributor(s) if they need to do anything unusual for
 297 the builds, such as doing a @qq{make clean / doc-clean} or
 298 switching git branches (not expected, but just in case...)
 299
 300 @item
 301 You don't need to be able to completely approve patches.  Make
 302 sure the patch meets whatever you know of the guidelines (for doc
 303 style, code indentation, whatever), and then send it on to the
 304 frog list or -devel for more comments.  If you feel confident
 305 about the patch, you can push it directly (this is mainly intended
 306 for docs and translations; code patches should almost always go to
 307 -devel before being pushed).
 308
 309 @item
 310 Keep track of patches from your contributor.  If you've sent a
 311 patch to -devel, it's your responsibility to pester people to get
 312 comments for it, or at very least add it to the google tracker.
 313
 314 @end enumerate
 315
 316