-@c -*- coding: us-ascii; mode: texinfo; -*-
+@c -*- coding: utf-8; mode: texinfo; -*-
+
+@include included/helpus.itexi
@node Introduction to contributing
@chapter Introduction to contributing
+This chapter presents a quick overview of ways that people can
+help LilyPond.
@menu
-* Overview of tasks::
-* For unix developers::
-* For other contributors::
+* Help us::
+* Overview of work flow::
+* Lilybuntu::
+* Mentors::
@end menu
-@node Overview of tasks
-@section Overview of tasks
-
-
-FIXME: The intro should contain the "help us" material from web/,
-quite possibly as the very first thing. This requires having a
-macro for it, which depends on issue 939.
-
+@node Help us
+@section Help us
-@node For unix developers
-@section For unix developers
+@helpusNeed
+@helpusTasks
-To download the LilyPond Git repository:
-
-@example
-git clone git://git.sv.gnu.org/lilypond.git
-@end example
-
-Documentation is built using Texinfo. Subscribe to the
-developers' mailing list at
-@uref{http://lists.gnu.org/mailman/listinfo/lilypond-devel} and
-send well-formed Git patches to @uref{mailto:lilypond-devel@@gnu.org} for
-discussion.
+@helpusProjects
-@node For other contributors
-@section For other contributors
+@node Overview of work flow
+@section Overview of work flow
+@cartouche
+@strong{Ultra-short summary for Unix developers}: source code is at
+@code{git://git.sv.gnu.org/lilypond.git}. Documentation is built
+with Texinfo, after pre-processing with @code{lilypond-book}.
+Send well-formed patches to @email{lilypond-devel@@gnu.org}.
+@end cartouche
-The LilyPond source code is maintained as a Git repository, which
-contains:
+Git is a @emph{version control system} that tracks the history of
+a program's source code. The LilyPond source code is maintained
+as a Git repository, which contains:
@itemize
@item
The @q{official} LilyPond Git repository is hosted by the GNU
Savannah software forge at @uref{http://git.sv.gnu.org}.
-Although, since Git uses a @q{distributed} model, technically
+Although, since Git uses a @emph{distributed} model, technically
there is no central repository. Instead, each contributor keeps a
complete copy of the entire repository (about 116M).
Changes made within one contributor's copy of the repository can
be shared with other contributors using @emph{patches}. A patch
-is a simple text file generated by the @code{git} program that
+is a simple text file generated by the @command{git} program that
indicates what changes have been made (using a special format).
If a contributor's patch is approved for inclusion (usually
through the mailing list), someone on the current development team
-will @emph{apply} (or @q{push}) the patch to the official
-repository.
-
-Compiling (@q{building}) LilyPond allows developers to see how
-changes to the source code affect the program itself. Compiling
-is also needed to package the program for specific operating
-systems or distributions. LilyPond can be compiled from a local
-Git repository (for developers), or from a downloaded tarball (for
-packagers). Compiling LilyPond is a rather involved process, and
-most contributor tasks do not require it.
+will @emph{push} the patch to the official repository.
+
+The Savannah software forge provides two separate interfaces for
+viewing the LilyPond Git repository online: @emph{cgit} and
+@emph{gitweb}. The cgit interface should work faster than gitweb
+in most situations, but only gitweb allows you to search through
+the source code using @command{grep}, which you may find useful.
+The cgit interface is at
+@uref{http://git.sv.gnu.org/cgit/lilypond.git/} and the gitweb
+interface is at
+@uref{http://git.sv.gnu.org/gitweb/?p=lilypond.git}.
+
+Git is a complex and powerful tool, but tends to be confusing at
+first, particularly for users not familiar with the command line
+and/or version control systems. Contributors who don't want to
+deal with Git directly are encouraged to use the
+@command{lily-git} graphical user interface instead.
+
+@emph{Compiling} (@q{building}) LilyPond allows developers to see
+how changes to the source code affect the program itself.
+Compiling is also needed to package the program for specific
+operating systems or distributions. LilyPond can be compiled from
+a local Git repository (for developers), or from a downloaded
+tarball (for packagers). Compiling LilyPond is a rather involved
+process, and most contributor tasks do not require it.
+
+Contributors can contact the developers through the
+@q{lilypond-devel} mailing list. The mailing list archive is
+located at
+@uref{http://lists.gnu.org/archive/html/lilypond-devel/}. If you
+have a question for the developers, search the archives first to
+see if the issue has already been discussed. Otherwise, send an
+email to @email{lilypond-devel@@gnu.org}. You can subscribe to
+the developers' mailing list here:
+@uref{http://lists.gnu.org/mailman/listinfo/lilypond-devel}.
+
+@warning{Contributors on Windows or MacOS X wishing to compile
+code or documentation are strongly advised to use @ref{Lilybuntu}
+instead of trying to install all software dependencies
+themselves.}
+
+
+@node Lilybuntu
+@section Lilybuntu
+
+It is not possible to compile LilyPond on Windows, and extremely
+difficulty to compile it on MacOS X. We have therefore made a
+@q{remix} of Ubuntu which includes all necessary dependencies to
+compile both LilyPond and the documentation. This can be run
+inside a virtual machine without disturbing your main operating
+system.
+
+@enumerate
+@item
+Install some virtualization software.
+
+Any virtualization tool can be used, but we recommend VirtualBox:
+
+@example
+@uref{http://@/www.virtualbox.org/@/wiki/@/Downloads}
+@end example
+
+In virtualization terminology, your main operating system is the
+@qq{host}.
+
+@item
+Download the @file{lilybuntu2.iso} disk image:
+
+@example
+@uref{http://files.lilynet.net/lilybuntu2.iso}
+@end example
+
+@advanced{There is a md5sum available:
+@uref{http://files.lilynet.net/lilybuntu2.iso.md5}}
+
+@item
+Install @file{lilybuntu2.iso} as the @qq{guest} operating system
+on your virtualized system.
+
+@itemize
+
+@item
+If possible, use at least 700 MB of RAM (1GB would be better) for
+the virtual machine, and use @qq{dynamically expanding storage}
+for the virtual hard drive. A complete compile of everything
+(code, docs, regression tests) can reach 10 GB.
+
+@item
+When @file{lilybuntu2.iso} boots, it shows an ISOLINUX
+@code{boot:} prompt. Type:
+
+@example
+install
+@end example
+
+@item
+At the @qq{Prepare disk space} stage, do not be afraid to select
+@qq{Erase and use the entire disk}, since this refers to your
+@emph{virtual disk}, not your machine's actual hard drive.
+
+@item
+After restarting your system, if you see the ISOLINUX @code{boot:}
+prompt again, go to
+@w{Devices@arrow{}CD/DVD Devices@arrow{}} and @emph{de-select}
+the @q{lilybuntu2.iso} option, then reboot.
+
+@end itemize
+
+@advanced{
+The latest version of lilybuntu is based on Ubuntu 10.04.1; if you
+encounter any difficulties installing it, search for one of the
+many tutorials for installing that particular version of Ubuntu as
+a client operating system.
+}
+
+@item
+Do any extra configuration for your virtualization software.
+
+VirtualBox has extra @qq{guest additions} which can make the
+virtualization easier to use (full-screen, easy file sharing
+between host and client operating systems, shared clipboards,
+etc).
+
+@enumerate
+
+@item
+From the @code{Devices} menu of VirtualBox, select @code{Install
+Guest Additions...}.
+
+@item
+From the @code{Places} menu of Ubuntu, select
+@code{VBOXADDITIONS_}. A file-system window will open.
+
+@item
+Double-click on the @file{autorun.sh} file, then select @qq{Run in
+Terminal}, and enter your password when prompted.
+
+@item
+Once the script is finished, reboot your Virtual Machine to
+complete the installation.
+
+@advanced{If you do any kernel upgrades, you may need to re-run
+these VBOXADDITIONS instructions.}
+
+@end enumerate
+
+If you use other virutalization software, then follow the normal
+procedures for your virtualization software with Ubuntu as the
+client.
+
+@advanced{not all hardware is supported in all virtualization
+tools. In particular, some contributors have reported problems
+with USB devices. If you would like to investigate further, then
+look for help for your virtualization tool using your normal OS as
+the @qq{host} and Ubuntu as the @qq{client}.}
+
+@end enumerate
+
+If you are not familiar with Linux, it may be beneficial to read a
+couple of @qq{introduction to Ubuntu} webpages.
+
+@itemize
+@item
+One particular change from Windows and MacOS X is that most
+software should be installed with your @qq{package manager}; this
+vastly simplifies the process of installing and configuring
+software. Go to
+@w{System@arrow{}Administration@arrow{}Synaptic Package Manager}.
+
+@item
+The rest of this manual assumes that you are using the
+command-line; go to
+@w{Applications@arrow{}Accessories@arrow{}Terminal}.
+
+@end itemize
+
+You should now progress to @ref{Using lily-git}.
+
+
+@node Mentors
+@section Mentors
+
+We have a semi-formal system of mentorship, similar to the
+medieval @qq{journeyman/master} training system. New contributors
+will have a dedicated mentor to help them @qq{learn the ropes}.
+
+@warning{This is subject to the availability of mentors; certain
+jobs have more potential mentors than others.}
+
+@subheading Contributor responsibilities
+
+@enumerate
+
+@item
+Ask your mentor which sections of the CG you should read.
+
+@item
+If you get stuck for longer than 10 minutes, ask your mentor.
+They might not be able to help you with all problems, but we find
+that new contributors often get stuck with something that could be
+solved/explained with 2 or 3 sentences from a mentor.
+
+@item
+Send patches to your mentor for initial comments.
+
+@item
+Inform your mentor if you're going to be away for a month, or if
+you leave entirely. Contributing to lilypond isn't for everybody;
+just let your mentor know so that we can reassign that work to
+somebody else.
+
+@item
+Inform your mentor if you're willing to do more work -- we always
+have way more work than we have helpers available. We try to
+avoid overwhelming new contributors, so you'll be given less work
+than we think you can handle.
+
+@end enumerate
+
+
+@subheading Mentor responsibilities
+
+@enumerate
+
+@item
+Respond to questions from your contributor(s) promptly, even if
+the response is just @qq{sorry, I don't know} or @qq{sorry, I'm
+very busy for the next 3 days; I'll get back to you then}. Make
+sure they feel valued.
+
+@item
+Inform your contributor(s) about the expected turnaround for your
+emails -- do you work on lilypond every day, or every weekend, or
+what? Also, if you'll be unavailable for longer than usual (say,
+if you normally reply within 24 hours, but you'll be at a
+conference for a week), let your contributors know. Again, make
+sure they feel valued, and that your silence (if they ask a
+question during that period) isn't their fault.
+
+@item
+Inform your contributor(s) if they need to do anything unusual for
+the builds, such as doing a @qq{make clean / doc-clean} or
+switching git branches (not expected, but just in case...)
+
+@item
+You don't need to be able to completely approve patches. Make
+sure the patch meets whatever you know of the guidelines (for doc
+style, code indentation, whatever), and then send it on to the
+frog list or -devel for more comments. If you feel confident
+about the patch, you can push it directly (this is mainly intended
+for docs and translations; code patches should almost always go to
+-devel before being pushed).
+
+@item
+Keep track of patches from your contributor. If you've sent a
+patch to -devel, it's your responsibility to pester people to get
+comments for it, or at very least add it to the google tracker.
+
+@end enumerate
+
projects / lilypond.git / blobdiff