[lilypond.git] / Documentation / contributor / introduction.itexi

@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
* Help us::
* Overview of work flow::
* Lilybuntu::
* Mentors::
@end menu


@node Help us
@section Help us

@helpusNeed

@helpusTasks

@helpusProjects


@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

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
all of the source files needed to build LilyPond, and

@item
a record of the entire history of every change made to every file
since the program was born.
@end itemize

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 @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 @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{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
When prompted to remove the installation CD, go to
@clicksequence{Devices @click{} CD/DVD Devices} and de-select
@file{lilybuntu2.iso}.

@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 guest 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 guest operating systems, shared clipboards, etc).

@enumerate

@item
In @emph{VirtualBox}, select @clicksequence{Devices @click{}
Install Guest Additions...}.

@item
In @emph{Ubuntu}, select @clicksequence{Places @click{}
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, restart Ubuntu to complete the
installation.

@item
Set up any additional features, such as @q{Shared Folders} between
your main operating system and ubuntu.  Consult external
documentation for this step.

@advanced{If you do any kernel upgrades, you may need to re-run
these VBOXADDITIONS instructions.}

@end enumerate

If you use other virtualization 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 @clicksequence{System @click{} Administration
@click{} Synaptic Package Manager}.

@item
The rest of this manual assumes that you are using the
command-line; go to @clicksequence{Applications @click{}
Accessories @click{} 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