X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=Documentation%2Fcontributor%2Fintroduction.itexi;h=24abc03bf7fb5b77cc3899a0b6a65a252d41fedf;hb=d40c9d6bdd81025c7c151e952712e85605d68c93;hp=914e7ef72b09ab8884a70284fdf6d1ad044031f3;hpb=aeda0cc2675a13ade10f3f97630ffa7dadd111aa;p=lilypond.git diff --git a/Documentation/contributor/introduction.itexi b/Documentation/contributor/introduction.itexi index 914e7ef72b..24abc03bf7 100644 --- a/Documentation/contributor/introduction.itexi +++ b/Documentation/contributor/introduction.itexi @@ -21,9 +21,9 @@ help LilyPond. @helpusNeed -@helpusTasks +@helpusSimple -@helpusProjects +@helpusAdvanced @node Overview of work flow @@ -47,27 +47,24 @@ 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 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 @@ -94,7 +91,7 @@ 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 Ubuntu +code or documentation are strongly advised to use our Debian LilyPond Developer Remix, as discussed in @ref{Quick start}.} @@ -112,20 +109,42 @@ hosted by GNU savannah. @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{Contacts}. +given on @rweb{Contact}. -@item @strong{branches}: +@item @strong{Git branches}: @itemize @item @code{master}: -base your work from this, but do @strong{not push} to it. +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}: -after a successful review (see below), push here. +always push to this branch after a successful patch review cycle (see +below). -@item @code{lilypond/translation}: -translators should base their work from this, and also push to it. +@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/}. @@ -133,74 +152,69 @@ 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. +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 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}. +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}. 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}. +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}. -@example -@uref{https://github.com/gperciva/git-cl} -@end example - -Your patch will be given @code{Patch-new} status. More info in -@ref{Uploading a patch for review}. +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 -If your patch passes some automatic tests, it will be given -@code{Patch-review} status. This generally happens within 24 -hours. +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 -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. +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 -The countdown is a 48-hour period which gives other developers a -chance to review the patch. If no significant problems are found, -your patch will be given @code{Patch-push} status. +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 -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. +Automatic scripts run every few hours to merge the @code{staging} branch +with @code{master}. @end enumerate -@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{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 @@ -279,8 +293,8 @@ 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).