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 b0948bafe15d853ce8eb9879839a277d828223ad..59eb050c1a2b59e38b3a33f64e6ffbb867fea71b 100644 (file)
--- 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 516a69ec3596cf42887ed5ace7a066882cf74f9e..ba4340dfd9cfea2a06ce722318ded4c35d547aab 100644 (file)
--- 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 250ad99d2e6ae476caa26d4d786b9728306ecac0..7d3c04e2aecf49193edb73195903528ff3f4acf5 100644 (file)
--- 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?