X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=Documentation%2Fcontributor%2Fintroduction.itexi;h=59eb050c1a2b59e38b3a33f64e6ffbb867fea71b;hb=da68c81eba74d8a968e0599e7de6c363f84ed3d8;hp=b708ca7a773bec3ab1401f88a08a8c7d39ada397;hpb=08666d43e1dd61b654c40a77d5785544065af423;p=lilypond.git diff --git a/Documentation/contributor/introduction.itexi b/Documentation/contributor/introduction.itexi index b708ca7a77..59eb050c1a 100644 --- a/Documentation/contributor/introduction.itexi +++ b/Documentation/contributor/introduction.itexi @@ -11,6 +11,7 @@ help LilyPond. @menu * Help us:: * Overview of work flow:: +* Summary for experienced developers:: * Mentors:: @end menu @@ -20,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 @@ -50,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. @@ -96,6 +90,103 @@ 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{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 @@ -120,6 +211,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. @@ -165,18 +262,41 @@ 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) -@end enumerate +@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