-@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::
+* Summary for experienced developers::
+* 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
+@helpusSimple
-To download the LilyPond Git repository:
-
-@example
-git clone git://git.sv.gnu.org/lilypond.git
-@end example
+@helpusAdvanced
-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.
+@node Overview of work flow
+@section Overview of work flow
-@node For other contributors
-@section For other contributors
+@advanced{Experienced developers should skip to
+@ref{Summary for experienced developers}.}
-
-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 @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
-indicates what changes have been made (using a special format).
+is a text file that indicates what changes have been made.
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:
+@uref{http://git.sv.gnu.org/cgit/lilypond.git/, cgit} and
+@uref{http://git.sv.gnu.org/gitweb/?p=lilypond.git, gitweb}.
+
+@ignore
+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.
+@end ignore
+
+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. We have created the
+@command{lily-git} graphical user interface to ease this
+difficulty.
+
@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 our Debian
+LilyPond Developer Remix, as discussed in @ref{Quick start}.}
+
+
+@node Summary for experienced developers
+@section Summary for experienced developers
+
+If you are already familiar with typical open-source tools, here's
+what you need to know:
+
+@itemize
+@item @strong{source repository}:
+hosted by GNU savannah.
+
+@example
+@uref{http://git.savannah.gnu.org/gitweb/?p=lilypond.git}
+@end example
+
+@item @strong{issue tracker}:
+currently hosted by Sourceforge.
+
+@example
+@uref{https://sourceforge.net/p/testlilyissues/issues/}
+@end example
+
+@item @strong{patch review}:
+Reitveld -- the collaborative code review tool.
+
+@example
+@uref{https://codereview.appspot.com}
+@end example
+
+@item @strong{environment variables}:
+many maintenance scripts, and many instructions in this guide rely on
+predefined @ref{Environment variables}.
+
+@item @strong{mailing lists}:
+given on @rweb{Contact}.
+
+@item @strong{Git branches}:
+
+@itemize
+@item @code{master}:
+always base your work from this branch, but @strong{never push} directly
+to it. Patches are always pushed directly to the @code{staging} branch
+instead.
+
+@item @code{staging}:
+always push to this branch after a successful patch review cycle (see
+below).
+
+@item @code{translation}:
+Translators should base their work on this branch only and push any
+translation patches directly to it as well.
+
+@item @code{dev/foo}:
+feel free to push any new branch name under @code{dev/}.
+
+@end itemize
+
+@item @strong{regression tests}:
+also known as @qq{regtests}. A collection of more than a thousand
+@code{.ly} files that are used to track LilyPond's engraving output
+between released stable and unstable versions as well as checked for all
+patches submitted for testing.
+
+If a patch introduces any unintentional changes to any of the regtests
+it is very likely it will be rejected (to be fixed) -- always make sure
+that, if you expect any regression test changes, that they are explained
+clearly as part of the patch description when submitting for testing.
+For more information see @ref{Regression tests}.
+
+@item @strong{reviews}:
+after finishing work on a patch or branch:
+
+@enumerate
+@item
+upload it with our custom @code{git-cl} @q{helper-script}; see
+@ref{git-cl}. In addition to uploading patches to the Google's Rietveld
+code review tool the script will also update the issue tracker (or add a
+new issue as appropriate) so that any reference to the patch is not
+lost. The current @qq{status} of any patch submitted is always managed
+on the issue tracker; also see @ref{Issues}.
+
+Once submitted the patch will be given a status of @code{Patch-new} and
+will enter the @qq{Patch Countdown}. More information on this can be
+found in the section @ref{Uploading a patch for review}.
+
+@item
+Patches are generally tested within 24 hours of submission. Once it has
+passed the basic tests -- make, make doc and a make test-baseline/check
+--, the tracker will be updated and the patch's status will change to
+@code{Patch-review} for other developers to examine.
+
+@item
+Every third day, the @qq{Patch Meister} will examine the issue tracker
+and the Rietveld code review tool for the submitted patch, looking for
+any comments by other developers. Depending on what has been posted,
+the patch will be either; @qq{moved on} to the next patch status
+(@code{Patch-countdown}); set back to @code{Patch-needs_work}; or if
+more discussion is needed, left at @code{Patch-review}. In all cases
+the issue tracker (not the Rietveld code review tool) will be updated by
+the Patch Meister accordingly.
+
+@item
+Once another three days have passed, any patch that has been given
+@code{Patch-countdown} status will be changed to @code{Patch-push}, the
+issue tracker is updated, and the developer can now push it directly to
+the @code{staging} branch (or email the patch -- created with
+@w{@code{git format-patch}} command -- to one of the other developers
+who can push it for you).
+
+@item
+Automatic scripts run every few hours to merge the @code{staging} branch
+with @code{master}.
+
+@end enumerate
+
+@advanced{This process does means that most patches will take about a
+week before finally being merged into @code{master}. With the limited
+resources for reviewing patches available and a history of unintended
+breakages in the @code{master} branch (from patches that have
+not had time to be reviewed properly), this is the best compromise we
+have found.}
+
+@end itemize
+
+
+@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
+If you have been working on a task much longer than was originally
+estimated, stop and ask your mentor. There may have been a
+miscommunication, or there may be some time-saving tips that could
+vastly simply your task.
+
+@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 -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. Either upload them
+to Rietveld yourself, or help+encourage them to upload the patches
+themselves. When a patch is on Rietveld, it's your responbility
+to get comments for it, and to add a link to the patch to the
+google tracker. (tag it @qq{patch-new}, or @qq{patch-review} if
+you feel very confident in it)
+
+@item
+Encourage your contributor to review patches, particularly your
+own! It doesn't matter if they're not familiar with C++ / scheme
+/ build system / doc stuff -- simply going through the process is
+valuable. Besides, anybody can find a typo!
+
+@item
+Contact your contributor at least once a week. The goal is just
+to get a conversation started -- there's nothing wrong with simply
+copy&pasting this into an email:
+
+@example
+Hey there,
+
+How are things going? If you sent a patch and got a review, do
+you know what you need to fix? If you sent a patch but have no
+reviews yet, do you know when you will get reviews? If you are
+working on a patch, what step(s) are you working on?
+@end example
+
+
+@end enumerate
+