@node Working with source code
@chapter Working with source code
-New contributors should only read @ref{Using lily-git}. Please
-ignore the rest of this chapter.
+@warning{New contributors should read @ref{Quick start}, and in
+particular @ref{lily-git}, instead of this chapter.}
-Advanced contributors will find the rest of this material quite
-useful, particularly if they are working on major new features.
+Advanced contributors will find this material quite useful,
+particularly if they are working on major new features.
@menu
-* Using lily-git::
+* Manually installing lily-git.tcl::
* Starting with Git::
* Basic Git procedures::
* Advanced Git procedures::
@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
+@node Manually installing lily-git.tcl
+@section Manually installing lily-git.tcl
-@command{lily-git.tcl} is a graphical tool to help you access and
-share changes to the lilypond source code.
+We have created an easy-to-use GUI to simplify git for new
+contributors. If you are comfortable with the command-line, then
+skip ahead to @ref{Starting with Git}.
-@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}
+@warning{These instructions are only for people who are @emph{not}
+using @ref{LilyDev}.}
-@subsubheading Lilybuntu
-
-@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
+@c there's some duplication in this section with stuff covered in
+@c Quick Start, but moving it into a macro inside included/ would
+@c be getting a bit icky. -gp
@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:
@c don't change the cgit link below to gitweb; gitweb uses
@c long filenames like "scripts_auxiliar_lily-git.tcl"
-@example
+@smallexample
@uref{http://git.sv.gnu.org/cgit/lilypond.git/plain/scripts/auxiliar/lily-git.tcl}
-@end example
+@end smallexample
@item
To run the program from the command line, navigate to the
@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.}
-
-
-@node Daily use of lily-git.tcl
-@unnumberedsubsec Daily use of @command{lily-git.tcl}
-
-@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.
-
-@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
-
-A single commit typically represents one logical set of related
-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 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
-
-You can go back and make changes to the most recent commit with
-the @qq{Amend previous commit} button. This is useful if a
-mistake is found after you have clicked the @qq{New local commit}
-button.
-
-To amend the most recent commit, re-edit the source files as
-needed and then click the @qq{Amend previous commit} button. The
-earlier version of the commit is not saved, but is replaced by the
-new one.
-
-@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}.}
-
-
-@subsubheading 3. Make patch set
-
-Before making a patch set from any commits, you should click the
-@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.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 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.
+Click on the @qq{Get source} button.
-@item
-Translators should send patches to
-@email{translations@@lilynet.net}.
+This will create a directory called @file{lilypond-git/} within
+your home directory, and will download the source code into that
+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}.
@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
-
+Navigate to the @file{lilypond-git/} directory to view the source
+files.
-@subsubheading The @qq{Abort changes -- Reset to origin} button
+@end enumerate
-@warning{Only use this if your local commit history gets
-hopelessly confused!}
+@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}.}
-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
-current state of the remote repository (at @code{git.sv.gnu.org}).
+Further instructions are in @ref{How to use lily-git}.
@node Starting with Git
@section Starting with Git
-
Using the Git program directly (as opposed to using the
@command{lily-git.tcl} GUI) allows you to have much greater control
over the contributing process. You should consider using Git if
@menu
* Setting up::
+* Git for the impatient::
+* Other repositories::
* Downloading remote branches::
@end menu
@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}.}
@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}).
(@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
+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
+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.
To configure settings that affect all repositories, use the
-@command{--global} command line option. For example, the first
+@option{--global} command line option. For example, the first
two options that you should always set are your @var{name} and
@var{email}, since Git needs these to keep track of commit
authors:
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
+Finally, and in some ways most importantly, let's make sure that
+we know what branch we're on. If you're not using LilyDev, add
+this to your @file{~/.bashrc}:
+
+@verbatim
+export PS1="\u@\h \w\$(__git_ps1)$ "
+@end verbatim
+
+If you are not using LilyDev, you may need to install the
+additional @code{git-completion} package, but it is definitely
+worth it.
+
@subsubheading Technical details
@end example
Using the @command{git@tie{}config} command @emph{without} the
-@command{--global} option configures repository-specific settings,
+@option{--global} option configures repository-specific settings,
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:
in this manual.
+@node Git for the impatient
+@subsection Git for the impatient
+
+@advanced{The intent of this subsection is to get you working on lilypond as
+soon as possible. If you want to learn about git, go read
+@ref{Other Git documentation}.
+@*
+Also, these instructions are designed to eliminate the most common
+problems we have found in using git. If you already know git and
+have a different way of working, great! Feel free to ignore the
+advice in this subsection.}
+
+
+Ok, so you've been using @command{lily-git.tcl} for a while, but
+it's time to take the next step. Since our review process delays
+patches by 60-120 hours, and you want to be able to work on other
+stuff while your previous work is getting reviewed, you're going
+to use @strong{branches}.
+
+You can think of a branch as being a separate copy of the source
+code. But don't worry about it.
+
+@subsubheading Start work: make a new branch
+
+Let's pretend you want to add a section to the Contributor's Guide
+about using branches.
+
+Start by updating the repository, then making a new branch. Call
+the branch anything you want as long as the name starts with
+@code{dev/}. Branch names that don't begin with @code{dev/} are
+reserved for special things in lilypond.
+
+@example
+git checkout master
+git pull -r origin master
+git branch dev/cg
+@end example
+
+@subsubheading Switch to that branch
+
+Nothing has happened to the files yet. Let's change into the new
+branch. You can think of this as @qq{loading a file}, although in
+this case it's really @qq{loading a directory and subdirectories
+full of files}.
+
+@example
+git checkout dev/cg
+@end example
+
+Your prompt now shows you that you're on the other branch:
+
+@example
+gperciva@@LilyDev:~/lilypond-git (dev/cg)$
+@end example
+
+To be able to manage multiple lilypond issues at once, you'll need to switch
+branches. You should have each lilypond issue on a separate branch.
+Switching branches is easy:
+
+@example
+git checkout master
+git checkout origin/staging
+git checkout origin/release/unstable
+git checkout dev/cg
+@end example
+
+Branches that begin with @code{origin/} are part of the remote repository,
+rather than your local repository, so when you check them out you get a
+temporary local branch. You should never make changes directly on a
+branch beginning with @code{origin/}. You get changes into the remote
+repository by making them in local branches, and then pushing them to
+@code{origin/staging} as described below.
+
+@subsubheading Make your changes
+
+Edit files, then commit them.
+
+@example
+git commit -a
+@end example
+
+
+Remember how I said that switching to a branch was like
+@qq{loading a directory}? Well, you've just @qq{saved a
+directory}, so that you can @qq{load} it later.
+
+@advanced{If you have used @command{cvs} or @command{svn}, you may
+be very confused: those programs use @qq{commit} to mean
+@qq{upload my changes to the shared source repository}.
+Unfortunately, just to be different, @w{@command{git commit}}
+means @qq{save my changes to the files}.}
+
+When you create a new file, you need to add it to git, then commit it:
+
+@example
+git add input/regression/avoid-crash-on-condition.ly
+git commit -a
+@end example
+
+
+Edit more files. Commit them again. Edit yet more files, commit
+them again. Go eat dinner. Switch to @code{master} so you can
+play with the latest changes from other developers. Switch back
+to your branch and edit some more. Commit those changes.
+
+At this stage, don't worry about how many commits you have.
+
+
+@subsubheading Save commits to external files
+
+Branches are nerve-wracking until you get used to them. You can
+save your hard work as individual @file{.patch} files. Be sure to
+commit your changes first.
+
+@example
+git commit -a
+git format-patch master
+@end example
+
+I personally have between 4 and 20 of those files saved in a
+special folder at any point in time. Git experts might laugh as
+that behavior, but I feel a @emph{lot} better knowing that I've
+got those backups.
+
+
+@subsubheading Prepare your branch for review
+
+After committing, you can update your branch with the latest master:
+
+@example
+git commit -a
+git checkout master
+git pull -r origin master
+git checkout dev/cg
+git rebase master
+@end example
+
+
+Due to the speed of lilypond development, sometimes
+@code{master} has changed so much that your branch can no
+longer be applied to it. In that happens, you will have a merge
+conflict. Stop for a moment to either cry or have a stiff drink,
+then proceed to @ref{Merge conflicts}.
+
+
+@subsubheading Upload your branch
+
+Finally, you're finished your changes. Time to upload for review.
+Make sure that you're on your branch, then upload:
+
+@example
+git checkout dev/cg
+git-cl upload master
+@end example
+
+
+@subsubheading Wait for reviews
+
+While you're waiting for a countdown and reviews, go back to
+master, make a @code{dev/doc-beams} branch, and start adding doc
+suggestions from issue 12345 from the tracker. Or make a
+@code{dev/page-breaks} and fix bug in page breaking. Or whatever.
+Don't worry, your @code{dev/cg} is safe.
+
+
+@subsubheading Combining commits (optional unless you have broken commits)
+
+Does the history of your branch look good?
+
+@example
+gitk
+@end example
+
+If you have a lot of commits on your branch, you might want to
+combine some of them. Alternately, you may like your commits, but
+want to edit the commit messages.
+
+@example
+git rebase -i master
+@end example
+
+Follow instructions on the screen.
+
+@warning{This step gives you the power to completely lose your
+work. Make a backup of your commits by saving them to
+@file{.patch} files before playing with this. If you do lose
+your work, don't despair. You can get it back by using @code{git reflog}.
+The use of @code{git reflog} is not covered here.}
+
+@warning{If any of the commits on your branch represent partial work that will
+not pass @var{make && make doc}, you @strong{must} squash these
+commits into a working commit. Otherwise, your push will break staging
+and will not be able to be merged to master. In general, you will
+be safer to have one commit per push.}
+
+
+@subsubheading Push to staging
+
+When you've got the coveted @code{Patch-push} status, time to
+prepare your upload:
+
+@example
+git fetch
+git rebase origin/staging dev/cg~0
+gitk HEAD
+@end example
+
+@warning{Do not skip the @command{gitk} step; a quick 5-second
+check of the visual history can save a great deal of frustration
+later on. You should see a set of your commits that are ahead of
+@code{origin/staging}, with no label for the top commit -- only a
+SHA1 id.}
+
+@warning{If @code{origin/staging} and @code{origin/master} are the
+same commit, your branch (@code{dev/cg} in the example) will also
+be at the top of the @code{gitk} tree. This is normal.}
+
+If everything looks good, push it:
+
+@example
+git push origin HEAD:staging
+@end example
+
+Then change back to your working branch:
+
+@example
+git checkout dev/cg
+@end example
+
+@warning{It is a best practice to avoid rebasing any of your branches
+to @code{origin/staging}. If @code{origin/staging} is broken, it
+will be deleted and rebuilt. If you have rebased one of your branches
+to @code{origin/staging}, the broken commits can end up in your branch.
+The commands given above do the rebase on a temporary branch, and avoid
+changing your working branch.}
+
+
+@subsubheading Delete your branch (safe)
+
+After a few hours, if there's nothing wrong with your branch, it
+should be automatically moved to @code{origin/master}. Update,
+then try removing your branch:
+
+@example
+git checkout master
+git pull -r origin master
+git branch -d dev/cg
+@end example
+
+The last command will fail if the contents of @code{dev/cg} are
+not present in @code{origin/master}.
+
+
+@subsubheading Delete your branch (UNSAFE)
+
+@c don't give explicit commands here -- this is too dangerous to copy and paste
+Sometimes everything goes wrong. If you want to remove a branch even though
+it will cause your work to be lost (that is, if the contents of @code{dev/cg}
+are @strong{not} present in master), follow the instructions in @qq{Delete
+your branch (safe)}, but replace the @code{-d} on the final line with
+a @code{-D}.
+
+
+@node Other repositories
+@subsection Other repositories
+
+We have a few other code repositories.
+
+@menu
+* lilypond-extra::
+* Grand Unified Builder (GUB)::
+* lilypad::
+* yet more repositories::
+@end menu
+
+@node lilypond-extra
+@unnumberedsubsubsec lilypond-extra
+
+There is a separate repository for general administrative scripts,
+as well as pictures and media files for the website. People
+interested in working on the website should download this
+repository, and set their @code{$LILYPOND_WEB_MEDIA_GIT}
+environment variable to point to that repository.
+
+@example
+@uref{https://github.com/gperciva/lilypond-extra}
+@end example
+
+To configure an environment variable in bash (the default for most
+GNU/Linux distributions),
+
+@example
+export LILYPOND_WEB_MEDIA_GIT=$HOME/dir/of/lilypond-extra/
+@end example
+
+Be aware that @code{lilypond-extra} is the definitive source for some binary
+files - in particular PDF versions of papers concerning LilyPond. To add
+further PDFs of this sort, all that is necessary is to add the PDF to
+@code{lilypond-extra} and then add a reference to it in the documentation. The
+file will then be copied to the website when @code{make website} is run.
+
+However, pictures that are also used in the documentation build are mastered in
+the main git repository. If any of these is changed, it should be updated in
+git, and then the updates copied to @code{lilypond-extra}.
+
+@node Grand Unified Builder (GUB)
+@unnumberedsubsubsec Grand Unified Builder (GUB)
+
+Another item of interest might be the Grand Unified Builder, our
+cross-platform building tool. Since it is used by other projects as
+well, it is not stored in our gub repository. For more info, see
+@uref{http://lilypond.org/gub}.
+
+There are two locations for this repository: the version being used to
+build lilypond, which is at
+
+@example
+@uref{http://github.com/gperciva/gub}
+@end example
+
+and the original version by Jan Nieuwenhuizen, kept at
+
+@example
+@uref{http://github.com/janneke/gub}
+@end example
+
+
+@node lilypad
+@unnumberedsubsubsec lilypad
+
+Our binary releases on MacOS X and Windows contain a lightweight
+text editor. This code is here:
+
+@example
+https://github.com/gperciva/lilypad
+@end example
+
+
+@node yet more repositories
+@unnumberedsubsubsec yet more repositories
+
+There are a few other repositories floating around, which will
+hopefully be documented in the near future.
+
+
@node Downloading remote branches
@subsection Downloading remote branches
+@warning{contains obsolete + misleading info}
@menu
* Organization of remote branches::
and the website. Generally, the @code{master} branch is expected
to compile successfully.
-The @code{lilypond/translation} branch is a side branch that
+The @code{translation} branch is a side branch that
allows translators to work without needing to worry about
compilation problems. Periodically, the Translation Meister
(after verifying that it doesn't break compilation), will
-@emph{merge} this branch back into @code{master} to incorporate
+@emph{merge} this branch into @code{staging} to incorporate
recent translations. Similarly, the @code{master} branch is
-usually merged into the @code{lilypond/translation} branch after
+usually merged into the @code{translation} branch after
significant changes to the English documentation. See
@ref{Translating the documentation} for details.
@node Downloading individual branches
@unnumberedsubsubsec Downloading individual branches
+@warning{obsolete, should be deleted!}
+
Once you have initialized an empty Git repository on your system
(see @ref{Initializing a repository}), you can download a remote
origin git://git.sv.gnu.org/lilypond.git/
@end example
-To download the @code{lilypond/translation} branch, enter:
+To download the @code{translation} branch, enter:
@example
-git remote add -ft lilypond/translation -m \
- lilypond/translation origin git://git.sv.gnu.org/lilypond.git/
+git remote add -ft translation -m \
+ translation origin git://git.sv.gnu.org/lilypond.git/
@end example
The @command{git@tie{}remote@tie{}add} process could take up to
@noindent
where @code{@var{branch}} is the name of your tracking branch,
-either @code{master} or @code{lilypond/translation}.
+either @code{master} or @code{translation}.
Git will issue some warnings; this is normal:
@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}.
@item @code{stable/XYZ}:
The branches are kept for archival reasons.
-@end itemize
+@item @code{archive/XYZ}:
+The branches are kept for archival reasons.
-Another item of interest might be the Grand Unified Builder, our
-cross-platform building tool. Since it is used by projects as
-well, it is not stored in our gub repository. For more info, see
-@uref{http://lilypond.org/gub}. The git location is
-@uref{http://github.com/janneke/gub}.
+@end itemize
@node Basic Git procedures
@end example
If you're tracking the remote @code{master} branch, you should add
-the @code{-r} option (short for @code{--rebase}) to keep commits
+the @option{-r} option (short for @option{--rebase}) to keep commits
on your local branch current:
@example
@end example
If you don't edit translated documentation and don't want to type
-@code{-r} every time, configure the master branch to rebase by
+@option{-r} every time, configure the master branch to rebase by
default with this command:
@example
you have not yet pushed to @code{git.sv.gnu.org}, please do not
rebase. If you want to avoid wondering whether you should rebase
each time you pull, please always use committishes from master
-and/or lilypond/translation branch on @code{git.sv.gnu.org}, which
+and/or translation branch on @code{git.sv.gnu.org}, which
in particular implies that you must push your changes to
documentation except committishes updates (possibly after having
rebased), then update the committishes and push them.}
@end example
Git will ask you for confirmation if it sees that data would be
-lost by deleting the branch. Use @code{-D} instead of @code{-d}
+lost by deleting the branch. Use @option{-D} instead of @option{-d}
to bypass this. Note that you cannot delete a branch if it is
currently checked out.
If any conflict happens, see @ref{Resolving conflicts}.
-There are common usage cases for merging: as a translator, you
-will often want to merge @code{master} into
-@code{lilypond/translation}; on the other hand, the Translations
-meister wants to merge @code{lilypond/translation} into
-@code{master} whenever he has checked that
-@code{lilypond/translation} builds successfully.
+There are common usage cases for merging: as a translator, you will
+often want the Translations meister to merge @code{master} into
+@code{translation}; on the other hand, the Translations meister wants
+to merge @code{translation} into @code{staging} whenever he has
+checked that @code{translation} builds successfully.
@node Commits and patches
@end example
@noindent
-The @code{-a} is short for @code{--all} which includes modified
+The @option{-a} is short for @option{--all} which includes modified
and deleted files, but only those newly created files that have
previously been added.
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
+should leave off the @option{-r}) before doing this to ensure that
your patches are as current as possible.
Once you have made one or more commits in your local repository,
@uref{http://codereview.appspot.com/}
@end example
-@subsubheading Initial setup
+@subsubheading @command{git-cl} install
+
+LilyDev users should skip over these @q{install} instructions.
@enumerate
@item
-You must have a gmail account.
+Install @command{git-cl} by entering:
+
+@example
+git clone https://github.com/gperciva/git-cl.git
+@end example
+
+If that command fails for some reason, try this instead:
+
+@example
+git clone git://github.com/gperciva/git-cl.git
+@end example
@item
-Install @command{git-cl} by entering:
+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}).
+
+In Ubuntu (and LilyDev), you can add directories to PATH
+by adding this line to a hidden file @file{.bashrc},
+located in your home directory:
@example
-git clone git://neugierig.org/git-cl.git
+PATH=~/type-here-directory-containing-git-cl:"$@{PATH@}"
@end example
+@end enumerate
+
+@subsubheading @command{git-cl} configuration
+
+LilyDev users should perform these @q{configuration} instructions.
+
+@enumerate
@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}).
+You must have a google account; please create one if you do not
+have one already.
+Note that a google account does not need to be a gmail account; you can
+use any email address for your google account when you sign up.
@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).
+Move into the top source directory and then configure @command{git
+cl} with the following commands:
@example
-cd $HOME/lilypond-git/
+cd $LILYPOND_GIT
git cl config
@end example
+For the @qq{Rietveld server} question, the default value
+(@qq{codereview.appspot.com}) should be accepted by
+answering with a newline (CR).
+
The @qq{CC list} question should be answered with:
@example
lilypond-devel@@gnu.org
@end example
+The @qq{Tree status URL} value should be left blank. So should
+the @qq{ViewVC URL} value, since it is used by @command{git cl
+dcommit} which is only for repositories which use @command{git
+svn} (LilyPond doesn't).
+
@end enumerate
@subsubheading Uploading patch set
git cl upload origin/master
@end example
+@c Mention staging here?
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.
+@c don't make this one an @example; we don't want to make it easy
+@c for people to use this accidently
+Notifications of patches are automatically added to our issue
+tracker to reduce the chance of patches getting lost. To suppress
+this (not recommended), add the @code{-n / --no-code-issue}
+option.
+
@item
@strong{Separate branch}: (complicated option)
@end itemize
+First you will see a terminal editor where you can edit the
+message that will accompany your patch. @command{git-cl} will
+respect the @env{EDITOR} environment variable if defined,
+otherwise it will use @command{vi} as the default editor.
+
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.
+@warning{Some installations of git-cl fail when uploading a patch
+with certain filename extensions. If this happens, it can
+generally be fixed by editing the list of exceptions at top of
+@file{git-cl.py}.}
+
@subsubheading Announcing your patch set
You should then announce the patch by logging into the code review
(mostly bogus) comment to your issue. The text of your comment
will be sent to our developer mailing list.
+@warning{There is no automatic notification of a new patch; you
+must add a comment yourself.}
+
@subsubheading Revisions
As revisions are made in response to comments, successive patch sets
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
It is possible to work with several branches on the same local Git
repository; this is especially useful for translators who may have
-to deal with both @code{lilypond/translation} and a stable branch,
+to deal with both @code{translation} and a stable branch,
e.g. @code{stable/2.12}.
Some Git commands are introduced first, then a workflow with
@menu
+* Merge conflicts::
* Advanced Git concepts::
* Resolving conflicts::
* Reverting all local changes::
* Git log::
* Applying remote patches::
* Sending and receiving patches via email::
+* Cleaning up multiple patches::
* Commit access::
+* Pushing to staging::
@end menu
+@node Merge conflicts
+@subsection Merge conflicts
+
+To be filled in later, and/or moved to a different section. I
+just wanted to make sure that I had a stub ready somewhere.
+
+
@node Advanced Git concepts
@subsection Advanced Git concepts
@noindent
where @code{@var{branch}} is typically @code{master} or
-@code{lilypond/translation}; if you do not know or remember, see
+@code{translation}; if you do not know or remember, see
@ref{Downloading remote branches} to remember which commands you
issued or which source code you wanted to get.
Sometimes git will become hopelessly confused, and you just want
to get back to a known, stable state. This command destroys any
-local changes you have made, but at least you get back to the
-current online version:
+local changes you have made in the currently checked-out branch,
+but at least you get back to the current online version:
@example
git reset --hard origin/master
@subsubheading Local clones, or having several working trees
If you play with several Git branches, e.g. @code{master},
-@code{lilypond/translation}, @code{stable/2.12}), you may want to
+@code{translation}, @code{stable/2.12}), you may want to
have one source and build tree for each branch; this is possible
with subdirectories of your local Git repository, used as local
cloned subrepositories. To create a local clone for the branch
Patches created without @code{git@tie{}format-patch} can be
applied in two steps. The first step is to apply the patch to the
-working tree:
+working tree and the index:
@example
-git apply @var{patch}
+git apply --index @var{patch}
@end example
@noindent
author of the patch. This can be done with the following command:
@example
-git commit -a --author="@var{John Smith} <@var{john@@example.com}>"
+git commit --author="@var{John Smith} <@var{john@@example.com}>"
@end example
+Please note that using the @code{--index} option for patching is quite
+important here and @emph{cannot} reliably be replaced by using the
+@code{-a} option when committing: that would only commit files from the
+working tree that are already registered with git, so every file that
+the patch actually @emph{adds}, like a regtest for a fixed bug, would
+get lost. For the same reason, you should not use the git-independent
+@samp{patch} program for applying patches.
@node Sending and receiving patches via email
@subsection Sending and receiving patches via email
@uref{http://wiki.winehq.org/GitWine}.
+@node Cleaning up multiple patches
+@subsection Cleaning up multiple patches
+
+If you have been developing on your own branch for a while, you
+may have more commmits than is really sensible. To revise your
+work and condense commits, use:
+
+@example
+git rebase origin/master
+git rebase -i origin/master
+@end example
+
+@warning{Be a bit cautious -- if you completely remove commits
+during the interactive session, you will... err... completely
+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
certificate in your browser, given at
@uref{http://savannah.gnu.org/tls/tutorial/}.
+@warning{Savannah will silently put your username in lower-case --
+do not try to use capital letters.}
+
@item
After registering, if you are not logged in automatically, login
@item
-Generate an SSH @q{dsa} key pair. Enter the following at the
+Generate an SSH @q{rsa} key pair. Enter the following at the
command prompt:
@example
-ssh-keygen -t dsa
+ssh-keygen -t rsa
@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_rsa}).
Next you are asked to enter an optional passphrase. On most
systems, if you use a passphrase, you will likely be prompted for
You can change/enable/disable your passphrase at any time with:
@example
-ssh-keygen -f ~/.ssh/id_dsa -p
+ssh-keygen -f ~/.ssh/id_rsa -p
@end example
Note that the GNOME desktop has a feature which stores your
@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_rsa} and your public key is saved as
+@file{~/.ssh/id_rsa.pub}.
@item
-Register your public SSH @q{dsa} key with Savannah. From the
+Register your public SSH @q{rsa} 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_rsa.pub} file into
one of the @qq{Authorized keys} text fields, and click
@qq{Update}.
@end example
@noindent
-where @var{user} is your username on Savannah.
+replacing @var{user} with your Savannah username.
@item
will include a @q{From} line that shows @q{ssh} as the protocol:
@example
-From ssh://@var{user}@@git.sv.gnu.org/srv/git/lilypond
+From ssh://git.sv.gnu.org/srv/git/lilypond
@end example
If the protocol shown is not @q{ssh}, check that you configured
@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
@noindent
Then @code{git@tie{}push} should work as before. For more
details, consult the @code{git@tie{}push} man page.
-@end enumerate
+@item
+Repeat the steps from generating an RSA key through to testing
+your commit access, for each machine from which you will be
+making commits, or you may simply copy the files from your
+local @file{~/.ssh} folder to the same folder on the other
+machine.
+
+@end enumerate
+
@subsubheading Technical details
@itemize
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.
+
+It may happen occasionally that the staging branch breaks automated
+testing. In this case the automatic move of staging material to
+master gets halted in order to avoid broken material entering master.
+This is a safety net. Please do not try breaking out from it by
+adding fixes on top of staging: in that case the whole sequence will
+end up in master after all, defeating the purpose of the system. The
+proper fix usually involves rewriting the staging branch and is best
+left to core developers after discussion on the developer list.
+
+@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
+gitk
+git push origin staging
+git checkout master
+@end example
+
+@warning{Do not skip the @command{gitk} step; a quick 5-second
+check of the visual history can save a great deal of frustration
+later on. You should only see that @command{staging} is only 1
+commit ahead of @code{origin/staging}.}
+
+@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
+gitk
+git push origin staging
+@end example
+
+@warning{Do not skip the @command{gitk} step; a quick 5-second
+check of the visual history can save a great deal of frustration
+later on. You should see that @code{staging} is only ahead of
+@code{origin/staging} by the commits from your branch.}
+
+
+
@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
@item
Book about git: @uref{http://progit.org/,Pro Git}
+
+@item
+Github help: @uref{http://help.github.com/}
+(very highly recommended by Graham)
+
@end itemize
projects / lilypond.git / blobdiff