X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=Documentation%2Fcontributor%2Fintroduction.itexi;h=24abc03bf7fb5b77cc3899a0b6a65a252d41fedf;hb=8f367da7d4611adadc083422f29703bc40e8488e;hp=bd81455328efc14d493cd784a1369f37a7c8bcfc;hpb=6f0d584555334a121bc26606cdfe60e3319ac3d0;p=lilypond.git diff --git a/Documentation/contributor/introduction.itexi b/Documentation/contributor/introduction.itexi index bd81455328..24abc03bf7 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 @@ -51,33 +47,30 @@ since the program was born. 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 @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 -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,116 +91,132 @@ 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 Debian +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: +@itemize +@item @strong{source repository}: +hosted by GNU savannah. @example -@uref{http://@/www.virtualbox.org/@/wiki/@/Downloads} +@uref{http://git.savannah.gnu.org/gitweb/?p=lilypond.git} @end example -In virtualization terminology, your main operating system is the -@qq{host}. +@item @strong{issue tracker}: +currently hosted by Sourceforge. -@item -Download the @file{lilybuntu.iso} disk image. +@example +@uref{https://sourceforge.net/p/testlilyissues/issues/} +@end example + +@item @strong{patch review}: +Reitveld -- the collaborative code review tool. @example -@uref{http://files.lilynet.net/lilybuntu2.iso} +@uref{https://codereview.appspot.com} @end example -@item -Install @file{lilybuntu.iso} as the @qq{client} operating system -on your virtualized system. +@item @strong{environment variables}: +many maintenance scripts, and many instructions in this guide rely on +predefined @ref{Environment variables}. -@itemize +@item @strong{mailing lists}: +given on @rweb{Contact}. -@item -The latest version of lilybuntu is based on Ubuntu 9.04; if you -encounter any difficulties installing it, search for one of the -many tutorials for installing Ubuntu 9.04 as a client operating -system. +@item @strong{Git branches}: -@item -When @file{lilybuntu.iso} boots, it automatically selects @qq{Try -Ubuntu without any change to your computer}; instead of this, you -must select @qq{Install Ubuntu}. +@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 -If possible, use at least 700 MB of RAM (1GB would be better) for -the virtual machine, and use a dynamically expanding virtual hard -drive. A complete compile of everything (code, docs, regression -tests) can reach 10 GB. +@item @code{staging}: +always push to this branch after a successful patch review cycle (see +below). -@item -At the partitioning stage, do not be afraid to select @qq{use -entire disk}, since this refers to your @emph{virtual disk}, not -your machine's actual hard drive. +@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 -Do any extra configuration for your virtualization software. +@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. -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). +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}. -@enumerate +@item @strong{reviews}: +after finishing work on a patch or branch: +@enumerate @item -From the @code{Devices} menu of VirtualBox, select @code{Install -Guest Additions...}. +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}. -@item -From the @code{Places} menu of Ubuntu, select -@code{VBOXADDITIONS_}. A file-system window will open. +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 -Double-click on the @file{autorun.sh} file, then select @qq{Run in -Terminal}. +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 -Once the script is finished, reboot your Virtual Machine to -complete the installation. +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. -@end enumerate +@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). -If you use other virutalization software, then follow the normal -procedures for your virtualization software with Ubuntu 9.04 as -the client. +@item +Automatic scripts run every few hours to merge the @code{staging} branch +with @code{master}. @end enumerate -Follow instructions for Linux when reading instructions about -@ref{Working with source code}, or @ref{Compiling}. +@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.} -@quotation -Advanced note: not all hardware is supported in all virtualization -tools. In particular, 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 quotation +@end itemize @node Mentors @@ -233,6 +242,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. @@ -278,16 +293,40 @@ 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 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