Doc: CG Updated section 1.3 - experienced devs

[lilypond.git] / Documentation / contributor / introduction.itexi

@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
* Help us::
* Overview of work flow::
* Summary for experienced developers::
* Mentors::
@end menu


@node Help us
@section Help us

@helpusNeed

@helpusSimple

@helpusAdvanced


@node Overview of work flow
@section Overview of work flow

@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
as a Git repository, which contains:

@itemize
@item
all of the source files needed to build LilyPond, and

@item
a record of the entire history of every change made to every file
since the program was born.
@end itemize

The @q{official} LilyPond Git repository is hosted by the GNU
Savannah software forge at @uref{http://git.sv.gnu.org}.

Changes made within one contributor's copy of the repository can
be shared with other contributors using @emph{patches}.  A patch
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
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