X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=Documentation%2Fcontributor%2Fintroduction.itexi;h=bb0f9849350575ddeccd4029a0a119aea85d5fac;hb=b5a72fde8d11be3bbcf2b78d98ece9e513c0de57;hp=ea97d4eb60b01d11689e1d81f194fe1401e792fc;hpb=2b1527a2afb87ea838b3f3861de92302277986ed;p=lilypond.git

diff --git a/Documentation/contributor/introduction.itexi b/Documentation/contributor/introduction.itexi
index ea97d4eb60..bb0f984935 100644
--- a/Documentation/contributor/introduction.itexi
+++ b/Documentation/contributor/introduction.itexi
@@ -11,7 +11,7 @@ help LilyPond.
 @menu
 * Help us::
 * Overview of work flow::
-* Lilybuntu::
+* Summary for experienced developers::
 * Mentors::
 @end menu
 
@@ -21,20 +21,16 @@ help LilyPond.
 
 @helpusNeed
 
-@helpusTasks
+@helpusSimple
 
-@helpusProjects
+@helpusAdvanced
 
 
 @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
+@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
@@ -53,7 +49,7 @@ 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).
+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
@@ -75,9 +71,9 @@ interface is at
 
 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.
+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.
@@ -98,138 +94,115 @@ 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.}
+code or documentation are strongly advised to use our Ubuntu
+LilyPond Developer Remix, as discussed in @ref{Quick start}.}
 
 
-@node Lilybuntu
-@section Lilybuntu
+@node Summary for experienced developers
+@section Summary for experienced developers
 
-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.
+If you are already familiar with typical open-source tools, here's
+what you need to know:
 
-@enumerate
-@item
-Install some virtualization software.
-
-Any virtualization tool can be used, but we recommend VirtualBox:
-
-@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{lilybuntu2.iso} disk image:
+@itemize
+@item @strong{source repository}:
+hosted by GNU savannah.
 
 @example
-@uref{http://files.lilynet.net/lilybuntu2.iso}
+@uref{http://git.savannah.gnu.org/gitweb/?p=lilypond.git}
 @end example
 
-@advanced{There is a md5sum available:
-@uref{http://files.lilynet.net/lilybuntu2.iso.md5}}
+@item @strong{mailing lists}:
+given on @rweb{Contacts}.
 
-@item
-Install @file{lilybuntu2.iso} as the @qq{guest} operating system
-on your virtualized system.
+@item @strong{branches}:
 
 @itemize
+@item @code{master}:
+base your work from this, but do @strong{not push} to it.
 
-@item
-If possible, use at least 700 MB of RAM (1GB would be better) for
-the virtual machine, and use @qq{dynamically expanding storage}
-for the virtual hard drive.  A complete compile of everything
-(code, docs, regression tests) can reach 10 GB.
+@item @code{staging}:
+after a successful review (see below), push here.
 
-@item
-When @file{lilybuntu2.iso} boots, it shows an ISOLINUX
-@code{boot:} prompt.  Type:
+@item @code{translation}:
+translators should base their work from this, and also push to it.
 
-@example
-install
-@end example
+@item @code{dev/foo}:
+feel free to push any new branch name under @code{dev/}.
 
-@item
-At the @qq{Prepare disk space} stage, do not be afraid to select
-@qq{Erase and use the entire disk}, since this refers to your
-@emph{virtual disk}, not your machine's actual hard drive.
+@end itemize
 
-@item
-After restarting your system, if you see the ISOLINUX @code{boot:}
-prompt again, go to
-@w{Devices@arrow{}CD/DVD Devices@arrow{}} and @emph{de-select}
-the @q{lilybuntu2.iso} option, then reboot.
+@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.
 
-@end itemize
+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}.
 
-@advanced{
-The latest version of lilybuntu is based on Ubuntu 10.04.1; if you
-encounter any difficulties installing it, search for one of the
-many tutorials for installing that particular version of Ubuntu as
-a client operating system.
-}
+@item @strong{reviews}:
+after finishing work on a patch or branch:
 
+@enumerate
 @item
-Do any extra configuration for your virtualization software.
+upload it with our custom @code{git-cl}.  In addition to uploading
+it to the google rietveld code review tool, this adds a tracker
+issue so that we don't lose your patch.  The @qq{status} of your
+patch is kept on the issue tracker; see @ref{Issues}.
 
-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).
+@example
+@uref{https://github.com/gperciva/git-cl}
+@end example
 
-@enumerate
+Your patch will be given @code{Patch-new} status.  More info in
+@ref{Uploading a patch for review}.
 
 @item
-From the @code{Devices} menu of VirtualBox, select @code{Install
-Guest Additions...}.
+If your patch passes some automatic tests, it will be given
+@code{Patch-review} status.  This generally happens within 24
+hours.
 
 @item
-From the @code{Places} menu of Ubuntu, select
-@code{VBOXADDITIONS_}.  A file-system window will open.
+After that, the patch must wait for the next @qq{patch countdown},
+which occur 3 times a week.  If there are a lot of patches waiting
+for a countdown, a subset of patches are chosen randomly.  When
+your patch is put on a countdown, it will be given
+@code{Patch-countdown} status.
 
 @item
-Double-click on the @file{autorun.sh} file, then select @qq{Run in
-Terminal}, and enter your password when prompted.
+The countdown is a 48-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
-Once the script is finished, reboot your Virtual Machine to
-complete the installation.
-
-@advanced{If you do any kernel upgrades, you may need to re-run
-these VBOXADDITIONS instructions.}
-
-@end enumerate
-
-If you use other virutalization software, then follow the normal
-procedures for your virtualization software with Ubuntu as the
-client.
+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
 
-Follow instructions for Linux when reading instructions about
-@ref{Working with source code}, or @ref{Compiling}.
-
-If you are not familiar with Linux, it may be benefitial to read a
-couple of @qq{introduction to Ubuntu} webpages.  One particular
-change from Windows and MacOS X is that most software should be
-installed with your @qq{package manager}; this vastly simplifies
-the process of installing and configuring software.  Go to
-@w{System@arrow{}Administration@arrow{}Synaptic Package Manager}.
-
+@advanced{Yes, this process means that most patches wait between
+60-120 hours before reaching 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.}
+
+@c I don't think this is important enough to list here, but I may
+@c change my mind and/or leave a link to a later CG section.
+@ignore
+@item @strong{code style}:
+C++ code should be formatted with
+@file{scripts/auxiliar/fixcc.py}, which requires
+@url{http://astyle.sourceforge.net/, astyle 2.02}.  However, we
+are not very strict about this requirement.
+
+At the moment, scheme code should be formatted @qq{like emacs does
+it}.  We are working on an automated tool to simplify this step.
+However, we are not very strict about this requirement either.
+@end ignore
 
-@advanced{not all hardware is supported in all virtualization
-tools.  In particular, some contributors have reported problems
-with USB devices.  If you would like to investigate further, then
-look for help for your virtualization tool using your normal OS as
-the @qq{host} and Ubuntu as the @qq{client}.
-}
+@end itemize
 
 
 @node Mentors
@@ -255,6 +228,12 @@ 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.
 
@@ -307,9 +286,33 @@ 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