@c -*- coding: utf-8; mode: texinfo; -*-
+@include included/helpus.itexi
+
@node Introduction to contributing
@chapter Introduction to contributing
-FIXME add fluff
+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
-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.
+@helpusNeed
+
+@helpusTasks
+
+@helpusProjects
@node Overview of work flow
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
@item
Inform your mentor if you're willing to do more work -- we always
-have way more work than we have helpers available.
+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
@item
Respond to questions from your contributor(s) promptly, even if
-the reponse is just @qq{sorry, I don't know} or @qq{sorry, I'm
+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.
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 thay feel valued, and that your silence (if they ask a
+sure they feel valued, and that your silence (if they ask a
question during that period) isn't their fault.
@item
@end enumerate
-
projects / lilypond.git / blobdiff