@end menu
+@c if you change this node name, you'll need to change the @ref in
+@c web/ and/or included/, along with all the translations.
@node Using lily-git
@section Using lily-git
-@subsubheading Install and Configuration
+@command{lily-git.tcl} is a graphical tool to help you access and
+share changes to the lilypond source code.
+
+@menu
+* Install and configuration of lily-git.tcl::
+* Daily use of lily-git.tcl::
+@end menu
+
+@node Install and configuration of lily-git.tcl
+@unnumberedsubsec Install and configuration of @command{lily-git.tcl}
+
+@subsubheading Lilybuntu
+
+@warning{The rest of this manual assumes that you are using the
+command-line; go to @clicksequence{Applications @click{}
+Accessories @click{} Terminal}.}
+
+@enumerate
+@item
+@code{lily-git.tcl} has already been install for you. Simply type
+(or copy&paste):
+
+@example
+cd
+wish lily-git.tcl
+@end example
+
+@item
+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
+@qq{Command output} window will display @qq{Done}, and the button
+label will change to say @qq{Update source}.
+
+@item
+Navigate to the @file{lilypond-git/} directory to view the source
+files. You should now be able to modify the source files using
+your normal text editor.
+
+@end enumerate
+
+You should now progress to @ref{Compiling with lilybuntu}.
+
+@warning{Throughout the rest of this manual, most command-line
+input should be entered from @file{~/lilypond-git/}. This is
+referred to as the @emph{top source directory}.}
+
+
+@subsubheading Other operating music systems
@enumerate
@item
@itemize
+@item
+Lilybuntu users: git has already been installed for you.
+
@item Windows users: download the @code{.exe} file labeled
@qq{Full installer for official Git} from:
@item
-Download the lily-git script from:
+Download the @command{lily-git.tcl} script from:
@c don't change the cgit link below to gitweb; gitweb uses
@c long filenames like "scripts_auxiliar_lily-git.tcl"
@item
To run the program from the command line, navigate to the
-directory containing @file{lily@/-git@/.tcl} and enter:
+directory containing @command{lily-git.tcl} and enter:
@example
wish lily-git.tcl
@end example
+@item
+Go read the lilybuntu instructions, starting from the @qq{get
+source} step.
+
@end enumerate
+@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.}
-@subsubheading 1. Get source / Update source
-When you click the @qq{Get source} button, @command{lily-git} 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
-@qq{Command output} window will display @qq{Done}, and the button
-label will change to say @qq{Update source}.
+@node Daily use of lily-git.tcl
+@unnumberedsubsec Daily use of @command{lily-git.tcl}
-Navigate to the @file{lilypond@/-git/} directory to view the source
-files. You should now be able to modify the source files using
-your normal text editor.
+@warning{Only work on one set of changes at once. Do not start
+work on any new changes until your first set has been accepted.}
+
+@subsubheading 1. Update source
+
+At the beginning of each session of lilypond work, you should
+click the @qq{Update source} button to get the latest changes to
+the source code.
-@quotation
-Advanced note: 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}, the
-@qq{Update source} button will take any new additions and add it
-to whatever is currently in your repository's history.
-@end quotation
+@warning{In some rare and unfortunate circumstances, this will
+result in a @emph{merge conflict}. If this occurs, follow the
+instructions for @qq{Abort changes}, below. Your work will not be
+lost.}
@subsubheading 2a. New local commit
changes (such as a bug-fix), and may incorporate changes to
multiple files at the same time.
-When you're finished making the changes for your first commit,
-click the @qq{New local commit} button. This will open the
-@qq{Git Commit Message} window. The message header is required,
-and the message body is optional. See @ref{Commits and patches}
-for more information regarding commits and commit messages.
+When you're finished making the changes for a commit, click the
+@qq{New local commit} button. This will open the @qq{Git Commit
+Message} window. The message header is required, and the message
+body is optional.
After entering a commit message, click @qq{OK} to finalize the
commit.
+@advanced{for more information regarding commits and commit
+messages, see @ref{Commits and patches}.}
+
@subsubheading 2b. Amend previous commit
earlier version of the commit is not saved, but is replaced by the
new one.
-Note that this does not update the patch @strong{files}; if you
+@warning{This does not update the patch @strong{files}; if you
have a patch file from an earlier version of the commit, you will
need to make another patch set when using this feature. The old
patch file will not be saved, but will be replaced by the new one
-after you click on @qq{Make patch set}.
+after you click on @qq{Make patch set}.}
@subsubheading 3. Make patch set
@qq{Update source} button to make sure the commits are based on
the most recent remote snapshot.
-When you click the @qq{Make patch set} button, @command{lily-git}
-will produce patch files for any new commits, saving them to the
-current directory. The command output will display the name of
-the new patch files near the end of the output:
+When you click the @qq{Make patch set} button,
+@command{lily-git.tcl} will produce patch files for any new
+commits, saving them to the current directory. The command output
+will display the name of the new patch files near the end of the
+output:
@example
0001-CG-add-lily-git-instructions.patch
Done.
@end example
-Send patch files to your mentor if you have one. Otherwise, write
-an email (must be less than 64 KB) to
-@email{lilypond-devel@@gnu.org} briefly explaining your work, with
-the patch files attached. Translators should send patches to
+Send patch files to the appropriate place:
+
+@itemize
+@item
+If you have a mentor, send it to them via email.
+
+@item
+New contributors should send the patch attached to an email to
+@email{frogs@@lilynet.net}. Please add @qq{[PATCH]} to the
+subject line.
+
+@item
+Translators should send patches to
@email{translations@@lilynet.net}.
+@item
+More experienced contributors should upload the patch for
+web-based review. This requires additional software and use of
+the command-line; see @ref{Uploading a patch for review}.
+
+@end itemize
+
@subsubheading The @qq{Abort changes -- Reset to origin} button
hopelessly confused!}
The button labeled @qq{Abort changes -- Reset to origin} will copy
-all changed files to a subdirectory of @file{lilypond@/-git/} named
-@file{aborted@/_edits/}, and will reset the repository to the
+all changed files to a subdirectory of @file{lilypond-git/} named
+@file{aborted_edits/}, and will reset the repository to the
current state of the remote repository (at @code{git.sv.gnu.org}).
Using the Git program directly (as opposed to using the
-@command{lily-git} GUI) allows you to have much greater control
+@command{lily-git.tcl} GUI) allows you to have much greater control
over the contributing process. You should consider using Git if
you want to work on complex projects, or if you want to work on
multiple projects concurrently.
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
+@file{~/lilypond-git/}, where @code{~} represents your home
directory). Run @command{git@tie{}init} from within the new
directory to initialize an empty repository:
@subsubheading Technical details
-This creates (within the @file{~/lilypond@/-git/} directory) a
+This creates (within the @file{~/lilypond-git/} directory) a
subdirectory called @file{.git/}, which Git uses to keep track of
changes to the repository, among other things. Normally you don't
need to access it, but it's good to know it's there.
@warning{Throughout the rest of this manual, all command-line
input should be entered from the top directory of the Git
-repository being discussed (eg. @file{~/lilypond@/-git/}). This is
-referred to as a @emph{top source directory}.}
+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
should configure some basic settings with the
Using the @command{git@tie{}config} command @emph{without} the
@command{--global} option configures repository-specific settings,
-which are stored in the file @file{.git/@/config}. This file is
+which are stored in the file @file{.git/config}. This file is
created when a repository is initialized (using
@command{git@tie{}init}), and by default contains these lines:
@end example
By now the source files should be accessible---you should be able
-to edit any files in the @file{lilypond@/-git/} directory using a
+to edit any files in the @file{lilypond-git/} directory using a
text editor of your choice. But don't start just yet! Before
editing any source files, learn how to keep your changes organized
and prevent problems later---read @ref{Basic Git procedures}.
@subsubheading Technical Details
The @command{git@tie{}remote@tie{}add} command should add some
-lines to your local repository's @file{.git/@/config} file:
+lines to your local repository's @file{.git/config} file:
@example
[remote "origin"]
The @command{git@tie{}config} command mentioned above adds the
line @code{rebase = true} to the master branch in your local
-repository's @file{.git/@/config} file:
+repository's @file{.git/config} file:
@example
[branch "master"]
* Making commits::
* Commit messages::
* Making patches::
+* Uploading a patch for review::
@end menu
@example
-# Please enter the commit message for your changes. Lines starting
+# Please enter the commit message for your changes. Lines starting
# with '#' will be ignored, and an empty message aborts the commit.
# On branch master
# Changes to be committed:
@node Making patches
@unnumberedsubsubsec Making patches
-
If you want to share your changes with other contributors and
developers, you need to generate @emph{patches} from your commits.
+We prefer it if you follow the instructions in
+@ref{Uploading a patch for review}. However, we present an
+alternate method here.
+
You should always run @command{git@tie{}pull@tie{}-r} (translators
should leave off the @code{-r}) before doing this to ensure that
your patches are as current as possible.
reviewed, the developers may push one or more of them to the main
repository or discuss them with you.
-@seealso
-If your patch includes a significant amount of code, you may want
-to see @ref{Adding or modifying features}, especially @emph{Post
-patch for comments}.
+@node Uploading a patch for review
+@unnumberedsubsubsec Uploading a patch for review
+
+Any non-trivial change should be uploaded to our @qq{Rietveld}
+code review website:
+
+@example
+@uref{http://codereview.appspot.com/}
+@end example
+
+@subsubheading Initial setup
+
+@enumerate
+
+@item
+You must have a gmail account.
+
+@item
+Install @command{git-cl} by entering:
+
+@example
+git clone git://neugierig.org/git-cl.git
+@end example
+
+@item
+Add the @file{git-cl/} directory to your PATH, or create a
+symbolic link to the @command{git-cl} and @command{upload.py}
+scripts in one of your PATH directories (such as
+@file{$HOME/bin}).
+
+
+@item
+Move into the top source directory and then configure
+@command{git cl}. If you do not understand any question, just
+answer with a newline (CR).
+
+@example
+cd $HOME/lilypond-git/
+git cl config
+@end example
+
+The @qq{CC list} question should be answered with:
+
+@example
+lilypond-devel@@gnu.org
+@end example
+
+@end enumerate
+
+@subsubheading Uploading patch set
+
+@warning{Unless you are familiar with branches, only work on one
+set of changes at once.}
+
+There are two methods, depending on your git setup.
+
+@itemize
+@item
+@strong{Master branch}: (easy option, and used in @command{lily-git.tcl})
+
+If you added your patch to @code{master}, then:
+
+@example
+git pull -r
+git cl upload origin/master
+@end example
+
+If you have git push ability, make sure that you @emph{remove}
+your patch (with @command{git rebase} or @command{git reset})
+before pushing other stuff.
+
+@item
+@strong{Separate branch}: (complicated option)
+
+Ensure your changes are committed in a separate branch, which
+should differ from the reference branch to be used by just the
+changes to be uploaded. If the reference branch is to be
+origin/master, ensure this is up-to-date. If necessary, use git
+rebase to rebase the branch containing the changes to the head of
+origin/master. Finally, check out branch with the changes and
+enter the command:
+
+@example
+git cl upload <reference SHA1 ID>
+@end example
+
+@noindent
+where <reference SHA1 ID> is the SHA1 ID of the commit to be used
+as a reference source for the patch. Generally, this will be the
+SHA1 ID of origin/master, and in that case the command:
+
+@example
+git cl upload origin/master
+@end example
+
+@noindent
+can be used.
+
+@end itemize
+
+After prompting for your Google email address and password, the
+patch set will be posted to Rietveld, and you will be given a URL
+for your patch.
+
+@subsubheading Announcing your patch set
+
+You should then announce the patch by logging into the code review
+issue webpage and using @qq{Publish + Mail Comments} to add a
+(mostly bogus) comment to your issue. The text of your comment
+will be sent to our developer mailing list.
+
+@subsubheading Revisions
+
+As revisions are made in response to comments, successive patch sets
+for the same issue can be uploaded by reissuing the git-cl command
+with the modified branch checked out.
+
+Sometimes in response to comments on revisions, the best way to
+work may require creation of a new branch in git. In order to
+associate the new branch with an existing Rietveld issue,
+the following command can be used:
+
+@example
+git cl issue issue-number
+@end example
+
+@noindent
+where @code{issue-number} is the number of the existing Rietveld
+issue.
+
+@subsubheading Resetting git cl
+
+If @command{git cl} becomes confused, you can @qq{reset} it by
+running:
+
+@example
+git cl issue 0
+@end example
@node Advanced Git procedures
@end example
When prompted for a location to save the key, press <ENTER> to
-accept the default location (@file{~/.ssh/@/id_dsa}).
+accept the default location (@file{~/.ssh/id_dsa}).
Next you are asked to enter an optional passphrase. On most
systems, if you use a passphrase, you will likely be prompted for
@end example
After setting up your passphrase, your private key is saved as
-@file{~/.ssh/@/id_dsa} and your public key is saved as
-@file{~/.ssh/@/id_dsa@/.pub}.
+@file{~/.ssh/id_dsa} and your public key is saved as
+@file{~/.ssh/id_dsa.pub}.
@item
Register your public SSH @q{dsa} key with Savannah. From the
@qq{My Account Configuration} page, click on @qq{Edit SSH Keys},
-then paste the contents of your @file{~/.ssh/@/id_dsa@/.pub} file into
+then paste the contents of your @file{~/.ssh/id_dsa.pub} file into
one of the @qq{Authorized keys} text fields, and click
@qq{Update}.
@end example
The list of known hosts is stored in the file
-@file{~/.ssh/@/known@/_hosts}.
+@file{~/.ssh/known_hosts}.
At this point, you are prompted for your passphrase if you have
one, then Git will attempt a pull.
@item
The @command{git@tie{}config} commands above should modify your
-local repository's @file{.git/@/config} file. These lines:
+local repository's @file{.git/config} file. These lines:
@example
[remote "origin"]
@item
Similarly, the
@command{git@tie{}config@tie{}push.default@tie{}matching} command
-should add these lines to @file{.git/@/config}:
+should add these lines to @file{.git/config}:
@example
[push]
@subsection Git GUI
Almost all subsequent work will use the Git Graphical User
-Interface, which avoids having to type command line commands. To
+Interface, which avoids having to type command line commands. To
start Git GUI first start the Git bash shell by clicking on the
desktop icon, and type
projects / lilypond.git / blobdiff