@menu
* Help us::
* Overview of work flow::
+* Summary for experienced developers::
* Mentors::
@end menu
@helpusNeed
-@helpusTasks
+@helpusSimple
-@helpusProjects
+@helpusAdvanced
@node Overview of work flow
@section Overview of work flow
-@cartouche
-@strong{Short summary for Unix developers}: source code is at
-@uref{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
+@advanced{Experienced developers should skip to
+@ref{Summary for experienced developers}.}
Git is a @emph{version control system} that tracks the history of
a program's source code. The LilyPond source code is maintained
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 116MB).
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).
+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: @emph{cgit} and
-@emph{gitweb}. The cgit interface should work faster than gitweb
+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.
-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}.
+@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
@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 Ubuntu
+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{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{branches}:
+
+@itemize
+@item @code{master}:
+base your work from this, but do @strong{not push} to it.
+
+@item @code{staging}:
+after a successful review (see below), push here.
+
+@item @code{translation}:
+translators should base their work from this, and also push to it.
+
+@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}; this is a collection of more than a
+thousand .ly files. We track the output of those files between
+versions.
+
+If a patch introduces any unintentional changes to the regtests,
+we will likely reject it -- make sure that you are aware and can
+explain any regtest changes. More info in @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 we don't lose reference to your
+patch. The @qq{status} of your patch is kept on the issue tracker;
+see @ref{Issues}.
+
+Your patch will be given @code{Patch-new} status. More information on
+this can be found in the section @ref{Uploading a patch for review}.
+
+@item
+If your patch passes some automatic tests, it will be given
+@code{Patch-review} status. This generally happens within 24
+hours.
+
+@item
+After that, the patch must wait for the next @qq{patch countdown},
+which occurs roughly every 3 days. When your patch is put on a
+countdown, it will be given @code{Patch-countdown} status.
+
+@item
+The countdown is a 72-hour period which gives other developers one
+last chance to review the patch. If no significant problems are
+found, your patch will be given @code{Patch-push} status.
+
+@item
+You may now either push it to the @code{staging} branch, or email
+your patch (created with @w{@code{git format-patch}}) to somebody
+who will push it for you.
+
+@end enumerate
+
+@advanced{Yes, this process means that most patches wait between
+60-120 hours before reaching @code{master}. This is unfortunate, but
+given our limited resources for reviewing patches and a history of
+unintended breakage in @code{master}, this is the best compromise
+we have found.}
+
+@end itemize
+
+
@node Mentors
@section Mentors
@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
+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. 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.
+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