From: James Lowe Date: Sat, 21 Nov 2015 21:47:47 +0000 (+0000) Subject: Doc - CG: Update information about git-cl X-Git-Tag: release/2.19.33-1~9^2~1 X-Git-Url: https://git.donarmstrong.com/?p=lilypond.git;a=commitdiff_plain;h=2a6b3329c46ae620dbe80dfaef076b13c5344911 Doc - CG: Update information about git-cl I have moved the information about how to download and configure git-cl - that was previously under the 'Commits and Patches' section - to its own @node (along side LilyDev and lily-git) under the 'quick start' section as it seemed unnecessarily hard to find in amongst all the other information, especially for new developers. I've added more explicit steps for LilyDev users - on how to update git-cl - and also, more generally, on how to 'configure' git cl, especially now that we are using Allura and need the extra login/bearer token requirements. --- diff --git a/Documentation/contributor/introduction.itexi b/Documentation/contributor/introduction.itexi index b0948bafe1..59eb050c1a 100644 --- a/Documentation/contributor/introduction.itexi +++ b/Documentation/contributor/introduction.itexi @@ -147,17 +147,15 @@ 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 we don't lose reference to 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}. +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 @@ -166,13 +164,11 @@ 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. +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 48-hour period which gives other developers one +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. @@ -189,20 +185,6 @@ 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 diff --git a/Documentation/contributor/quick-start.itexi b/Documentation/contributor/quick-start.itexi index 516a69ec35..ba4340dfd9 100644 --- a/Documentation/contributor/quick-start.itexi +++ b/Documentation/contributor/quick-start.itexi @@ -10,6 +10,7 @@ for you and will help you do this as quickly and easily as possible. @menu * LilyDev:: * lily-git:: +* git-cl:: * Compiling with LilyDev:: * Now start work!:: @end menu @@ -433,6 +434,176 @@ all changed files to a subdirectory of @file{$LILYPOND_GIT} named current state of the remote repository (at @code{git.sv.gnu.org}). +@node git-cl +@section git-cl + +@menu +* Installing git-cl:: +* Updating git-cl:: +* Configuring git-cl:: +@end menu + +Git-cl is a @q{helper script} that uploads patches to Google's Rietveld +Code Review Tool -- used by the developers for patch review -- and, at +the same time, updates LilyPond's issue tracker. + + +@node Installing git-cl +@unnumberedsubsec Installing @code{git-cl} + +@warning{LilyDev users can jump straight to the next section on updating +@command{git-cl} as it will already be installed in your home +directory.} + +@enumerate + +@item +Download @command{git-cl} by running the command: + +@example +git clone https://github.com/gperciva/git-cl.git +@end example + +@noindent +or, if that command fails for any reason, try: + +@example +git clone git://github.com/gperciva/git-cl.git +@end example + +@item +Add the @file{git-cl/} directory to your @var{PATH} or create a symbolic +link to the @command{git-cl} and @command{upload.py} scripts in one of +your @var{PATH} directories (e.g. @file{$HOME/bin}). + +In GNU/Linux you can add directories to @var{PATH} by adding this line +to your @file{.bashrc} file located in your home directory: + +@example +PATH=~/directory_containing_git-cl:"$@{PATH@}" +@end example + +@end enumerate + + +@node Updating git-cl +@unnumberedsubsec Updating @code{git-cl} + +LilyDev users should always make sure that they alwsys have the latest +version of git-cl installed. It is possible that changes may have been +made to git-cl that are not (yet) included in the version of LilyDev has +been installed. + +@noindent +Using a terminal run the following commands: + +@example +cd ~/git-cl/ +git pull +@end example + +This will download and update you to the lastest version of git-cl. + + +@node Configuring git-cl +@unnumberedsubsec Configuring @code{git-cl} + +@subsubheading Set up login accounts + +Because the @code{git-cl} updates two separate websites (Google's +Rietveld Code Review Tool and LilyPond's issue tracker) you @emph{must} +have a valid user login and password to both sites. + +@noindent +Although that it may appear that you have to use a @q{Google} email +address for the Rietveld Code Review Tool when you sign up, you can +instead select the option @qq{I prefer to use my current email address} +during sign up. + +@noindent +For a user login to the LilyPond issue tracker, please send your +request, preferably using the email address you want to use for your +login, to the LilyPond Developer's mailing list +(@code{lilypond-devel@@gnu.org}). + +@subsubheading Authorising git-cl for the LilyPond issue tracker + +The @code{git-cl} command itself also needs to be @q{authorized} so that +it can access the LilyPond issue tracker. + +@enumerate +@item +Once a valid login has been given for the LilyPond issye tracker, go to +the @q{Account settings} and select the @q{OAuth} tab. + +@item +Locate the @q{Register New Application} section and enter @code{git-cl} +in the @q{Application Name:} field. + +@item +Click on the @q{Register new application} button. You should now see +@q{git-cl} listed under the @q{My Applications} section. + +@item +Click on the @q{Generate Bearer Token} button. You should now see +@q{git-cl} listed under the @q{Authorized Applications} section along +with a value for the @q{Bearer Token} entry. This value is used, in the +next steps, to allow git-cl to access and update the LilyPond issue +tracker. + +@end enumerate + +@subsubheading Running git-cl for the first time + +@enumerate +@item +Using a terminal, move to top source directory of the +@code{$LILYPOND_GIT} directory and then run @code{git-cl} with the +@code{config} option: + +@example +cd $LILYPOND_GIT +git-cl config +@end example + +@item +When prompted for the @code{Rietveld server}: + +@example +Rietveld server (host[:port]) [codereview.appspot.com]: +@end example + +@item +When prompted for the @code{Allura server} (the LilyPond issue tracker): + +@example +Allura server [https://sourceforge.net/p/testlilyissues/issues/]: +@end example + +@item +When prompted for the @code{Allura bearer token} copy/paste the value +generated in the previous steps for +@emph{Authorising git-cl for the LilyPond issue tracker}: + +@smallexample +Allura bearer token (see https://sourceforge.net/auth/oauth/) [fdbfca60801533465480]: +@end smallexample + +@warning{The above is a @q{fake} bearer token just to illustrate the +example. Do not use this value.} + +@item +Finally, when prompted for the @code{CC list} entry, add the Lilypond +Developer's group email. + +@example +CC list ("x" to clear) [lilypond-devel@@gnu.org]: +@end example + +@end enumerate + +The @code{git-cl} script should now be correctly configured for use. + @node Compiling with LilyDev @section Compiling with LilyDev diff --git a/Documentation/contributor/source-code.itexi b/Documentation/contributor/source-code.itexi index 250ad99d2e..7d3c04e2ae 100644 --- a/Documentation/contributor/source-code.itexi +++ b/Documentation/contributor/source-code.itexi @@ -1383,6 +1383,9 @@ svn} (LilyPond doesn't). @subsubheading Uploading patch set +This section assumes that you have already configured the +@command{git-cl} @q{helper-script}. See @ref{git-cl}. + @warning{Unless you are familiar with branches, only work on one set of changes at once.} @@ -1396,7 +1399,7 @@ If you added your patch to @code{master}, then: @example git pull -r -git cl upload origin/master +git-cl upload origin/master @end example @c Mention staging here?