-@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{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 @q{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{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:
+@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
+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 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
+
projects / lilypond.git / blobdiff