From: Mike Solomon Date: Sat, 10 Dec 2011 10:22:07 +0000 (+0100) Subject: Merge branch 'staging' of ssh://git.sv.gnu.org/srv/git/lilypond into staging X-Git-Tag: release/2.15.22-1~20 X-Git-Url: https://git.donarmstrong.com/?a=commitdiff_plain;h=a5be31d893c3a738d87d07d18d6db8fa725e8efc;hp=975c00a63710da2472f57fbb6d5a484541f27c66;p=lilypond.git Merge branch 'staging' of ssh://git.sv.gnu.org/srv/git/lilypond into staging --- diff --git a/Documentation/contributor/introduction.itexi b/Documentation/contributor/introduction.itexi index 90829b4aaf..914e7ef72b 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 @@ -28,12 +29,8 @@ help LilyPond. @node Overview of work flow @section Overview of work flow -@cartouche -@strong{Short summary for Unix developers}: source code is at -@uref{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 @@ -101,6 +98,113 @@ code or documentation are strongly advised to use our Ubuntu 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{mailing lists}: +given on @rweb{Contacts}. + +@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{lilypond/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}. 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}. + +@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}. + +@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 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 +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. + +@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 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 + +@end itemize + + @node Mentors @section Mentors diff --git a/Documentation/contributor/issues.itexi b/Documentation/contributor/issues.itexi index a4b114d267..86976fd324 100644 --- a/Documentation/contributor/issues.itexi +++ b/Documentation/contributor/issues.itexi @@ -769,6 +769,15 @@ email should contain a link to the issue you just added. @warning{This is not a Bug Squad responsibility; we have a separate person handling this task.} +For contributors/developers: follow the steps in +@ref{Commits and patches}, and @ref{Pushing to staging}. + +For people doing maintenance tasks: git-cl is adding issues, James +is testing them, Colin is selecting them for countdowns, and +Patchy is merging from staging to master. In the coming weeks, +these tasks will be more and more automated. + +@ignore There is a single Patch Meister, and a number of Patch Helpers (rename this?). The list of known patches awaiting review is: @@ -807,6 +816,7 @@ message) on the webgit page: @uref{http://git.savannah.gnu.org/gitweb/?p=lilypond.git} @end example @end ignore +@ignore @item If the patch is clearly in response to an existing issue, then @@ -884,7 +894,7 @@ weeks. @end itemize - +@end ignore @node Summary of project status diff --git a/Documentation/contributor/quick-start.itexi b/Documentation/contributor/quick-start.itexi index 9a23906da4..d6d7e24d4f 100644 --- a/Documentation/contributor/quick-start.itexi +++ b/Documentation/contributor/quick-start.itexi @@ -52,7 +52,7 @@ Any virtualization tool can be used, but we recommend VirtualBox: @end example In virtualization terminology, your main operating system is the -@qq{host}, while lilydev is the @qq{guest}. +@strong{host}, while lilydev is the @strong{guest}. @item Download the Ubuntu LilyPond Developer Remix disk image: @@ -71,7 +71,7 @@ recognize what they are, then you don't want them: } @item -Create a music new @qq{virtual machine} inside your virtualization +Create a new @qq{virtual machine} inside your virtualization software. If possible, use at least 700 MB of RAM (1GB would be better) for @@ -80,7 +80,7 @@ for the virtual hard drive. A complete compile of everything (code, docs, regression tests) can reach 10 GB. @item -Install @file{ubuntu-lilydev-remix-1.1.iso} as the @qq{guest} +Install @file{ubuntu-lilydev-remix-1.1.iso} as the @strong{guest} operating system on your virtualized system. @enumerate @@ -96,7 +96,8 @@ install @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. +@strong{@emph{virtual disk}}, not your machine's actual hard +drive. @item When prompted to remove the installation CD, go to @@ -223,7 +224,7 @@ Right-click allows you to edit a file with gedit. We recommend using gedit. @item -Some contributors have recommended: (pdf available for free) +Some contributors have recommended a free pdf: @example @uref{http://www.ubuntupocketguide.com/} @@ -263,7 +264,7 @@ Click on the @qq{Get source} button. This will create a directory called @file{lilypond-git/} within your home directory, and will download the source code into that -directory (around 121Mb). When the process is finished, the +directory (around 150@tie{}Mb). When the process is finished, the @qq{Command output} window will display @qq{Done}, and the button label will change to say @qq{Update source}. diff --git a/Documentation/contributor/source-code.itexi b/Documentation/contributor/source-code.itexi index 27d8236b64..de292c99f6 100644 --- a/Documentation/contributor/source-code.itexi +++ b/Documentation/contributor/source-code.itexi @@ -82,7 +82,7 @@ Click on the @qq{Get source} button. This will create a directory called @file{lilypond-git/} within your home directory, and will download the source code into that -directory (around 55Mb). When the process is finished, the +directory (around 150@tie{}Mb). When the process is finished, the @qq{Command output} window will display @qq{Done}, and the button label will change to say @qq{Update source}. @@ -98,13 +98,6 @@ referred to as the @emph{top source directory}.} Further instructions are in @ref{Daily use of lily-git.tcl}. -@advanced{the @qq{Get source} button does not fetch the entire -history of the git repository, so utilities like @command{gitk} -will only be able to display the most recent additions. As you -continue to work with @command{lily-git.tcl}, the @qq{Update -source} button will take any new additions and add it to whatever -is currently in your repository's history.} - @node Starting with Git @section Starting with Git @@ -125,10 +118,6 @@ multiple projects concurrently. @node Setting up @subsection Setting up - -TODO: Remove this note if incorporating Windows instructions -throughout this section: - @warning{These instructions assume that you are using the command-line version of Git 1.5 or higher. Windows users should skip to @ref{Git on Windows}.} @@ -143,10 +132,9 @@ skip to @ref{Git on Windows}.} @node Installing Git @unnumberedsubsubsec Installing Git - If you are using a Unix-based machine, the easiest way to download and install Git is through a package manager such as @command{rpm} -or @command{apt-get}---the installation is generally automatic. +or @command{apt-get} -- the installation is generally automatic. The only required package is (usually) called @command{git-core}, although some of the auxiliary @command{git@var{*}} packages are also useful (such as @command{gitk}). @@ -155,25 +143,19 @@ Alternatively, you can visit the Git website (@uref{http://git-scm.com/}) for downloadable binaries and tarballs. -TODO: add Windows installation instructions (or @@ref@{Git on -Windows@}). - @node Initializing a repository @unnumberedsubsubsec Initializing a repository - -Once Git is installed, you'll need to create a new directory where -your initial repository will be stored (the example below uses -@file{~/lilypond-git/}, where @code{~} represents your home -directory). Run @command{git@tie{}init} from within the new -directory to initialize an empty repository: +Once Git is installed, get a copy of the source code: @example -mkdir ~/lilypond-git/; cd ~/lilypond-git/ -git init +git clone git://git.sv.gnu.org/lilypond.git ~/lilypond-git @end example +The above command will put the it in @file{~/lilypond-git}, where +@code{~} represents your home directory. + @subsubheading Technical details This creates (within the @file{~/lilypond-git/} directory) a @@ -190,7 +172,7 @@ input should be entered from the top directory of the Git repository being discussed (eg. @file{~/lilypond-git/}). This is referred to as the @emph{top source directory}.} -Before downloading a copy of the main LilyPond repository, you +Before working with the copy of the main LilyPond repository, you should configure some basic settings with the @command{git@tie{}config} command. Git allows you to set both global and repository-specific options. @@ -224,9 +206,6 @@ change the default editor to @command{nano}, enter: git config --global core.editor @var{nano} @end example -TODO: Add instructions for changing the editor on Windows, which -is a little different, I think. -mp - @subsubheading Technical details Git stores the information entered with @@ -1076,6 +1055,23 @@ running: git cl issue 0 @end example +@subsubheading Wait for a countdown + +Your patch will be available for reviews for the next few hours or +days. Three times a week, patches with no known problems are +gathered into a @qq{patch countdown} and their status changed to +@code{patch-countdown}. The countdown is a 48-hour waiting period +in which any final reviews or complaints should be made. + +During the countdown, your patch may be set to +@code{patch-needs_work}, indicating that you should fix something +(or at least discuss why the patch needs no modification). If no +problems are found, the patch will be set to @code{patch-push}. + +Once a patch has @code{patch-push}, it should be sent to your +mentor for uploading. If you have git push ability, look at +@ref{Pushing to staging}. + @node Advanced Git procedures @section Advanced Git procedures @@ -1104,6 +1100,7 @@ several Git branches of LilyPond source code is presented. * Sending and receiving patches via email:: * Cleaning up multiple patches:: * Commit access:: +* Pushing to staging:: @end menu @@ -1390,7 +1387,6 @@ remove those commits.} @node Commit access @subsection Commit access - Most contributors are not able to commit patches directly to the main repository---only members of the LilyPond development team have @emph{commit access}. If you are a contributor and are @@ -1567,6 +1563,9 @@ Git properly in the previous step. @item Test your commit access with a dry run: +@warning{Do not push directly to master; instead, push to staging. +See @ref{Pushing to staging}.} + @example git push --dry-run --verbose @end example @@ -1658,9 +1657,54 @@ broadband may use a slightly smaller MTU for efficient transmission over ATM. If this problem is encountered a possible work-around is to set the MTU in the local router to 1500. + +@node Pushing to staging +@subsection Pushing to staging + +Do not push directly to the git @code{master} branch. Instead, +push to @code{staging}. + +You will not see your patch on @code{origin/master} until some +automatic tests have been run. These tests are run every couple +of hours; please wait at least 12 hours before wondering if your +patch has been lost. Note that you can check the commits on +@code{origin/staging} by looking at the git web interface on +savannah. + +@subsubheading If your work is in a patch file + +Assuming that your patch is in a file called +@file{0001-my-patch.patch}, and you are currently on git master, +do: + +@example +git checkout staging +git pull -r +git am 0001-my-patch.patch +git push origin staging +git checkout master +@end example + +@subsubheading If your work is in a branch + +If you are working on branches and your work in is +@code{my_branch_name}, then do: + +@example +git checkout staging +git pull -r +git merge my_branch_name +git push origin staging +@end example + + + @node Git on Windows @section Git on Windows +@warning{We heavily recommend that development be done with our +virtual machine @ref{Lilydev}.} + @c Some of this may duplicate stuff in other sections @c But it is probably best for windows users to have it all together @c If necessary, clear this up later -td