-@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 For unix developers
-@section For unix developers
-
+@node Help us
+@section Help us
-To download the LilyPond Git repository:
+@helpusNeed
-@example
-git clone git://git.sv.gnu.org/lilypond.git
-@end example
+@helpusTasks
-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
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{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
tarball (for packagers). Compiling LilyPond is a rather involved
process, and most contributor tasks do not require it.
-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.
+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
+Open Source Edition (lower half of the linked page):
+
+@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{lilybuntu.iso} disk image.
+
+@example
+@uref{http://@/files.lilynet.net/@/lilybuntu.iso}
+@end example
+
+@item
+Install @file{lilybuntu.iso} as the @qq{client} operating system
+on your virtualized system.
+
+The latest version of lilybuntu is based on Ubuntu 9.04; if you
+encounter any difficulties installing it, search for one of the
+many tutorials for installing Ubuntu 9.04 as a client operating
+system.
+
+If possible, use at least 700 MB of RAM (1GB would be better) for
+the virtual machine, and use a dynamically expanding virtual hard
+drive. A complete compile of everything (code, docs, regression
+tests) can reach 10 GB.
+
+@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). Follow the normal procedures for your virtualization
+software with Ubuntu 9.04 as the client.
+
+@end enumerate
+
+Follow instructions for Linux when reading instructions about
+@ref{Working with source code}, or @ref{Compiling}.
@node 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