]> git.donarmstrong.com Git - lilypond.git/blobdiff - Documentation/contributor/source-code.itexi
CG: add warning about announcing a patch.
[lilypond.git] / Documentation / contributor / source-code.itexi
index 3223dfb9b31613e4124ad70f7d056f169c928c27..54d8ba7d7e7d94affcf3fb73c395d2129f385cdc 100644 (file)
@@ -4,14 +4,14 @@
 @node Working with source code
 @chapter Working with source code
 
 @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{Using 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
 
 @menu
-* Using lily-git::
+* Manually installing lily-git.tcl::
 * Starting with Git::
 * Basic Git procedures::
 * Advanced Git procedures::
 * Starting with Git::
 * Basic Git procedures::
 * Advanced Git procedures::
@@ -21,54 +21,19 @@ useful, particularly if they are working on major new features.
 @end menu
 
 
 @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}.
-
-
-@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
 
 @enumerate
 @item
@@ -76,9 +41,6 @@ If you haven't already, download and install Git.
 
 @itemize
 
 
 @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 Windows users: download the @code{.exe} file labeled
 @qq{Full installer for official Git} from:
 
@@ -116,11 +78,26 @@ wish lily-git.tcl
 @end example
 
 @item
 @end example
 
 @item
-Go read the lilybuntu instructions, starting from the @qq{get
-source} step.
+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.
 
 @end enumerate
 
 
 @end enumerate
 
+@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}.}
+
+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
 @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
@@ -129,116 +106,9 @@ source} button will take any new additions and add it to whatever
 is currently in your repository's history.}
 
 
 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.
-
-@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
-
-@warning{Only use this if your local commit history gets
-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
-current state of the remote repository (at @code{git.sv.gnu.org}).
-
-
 @node Starting with Git
 @section Starting with 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
 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
@@ -318,7 +188,7 @@ 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
 @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}.}
+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
 
 Before downloading a copy of the main LilyPond repository, you
 should configure some basic settings with the
@@ -1044,12 +914,11 @@ code review website:
 @uref{http://codereview.appspot.com/}
 @end example
 
 @uref{http://codereview.appspot.com/}
 @end example
 
-@subsubheading Initial setup
+@subsubheading @command{git-cl} install
 
 
-@enumerate
+LilyDev users should skip over these @q{install} instructions.
 
 
-@item
-You must have a gmail account.
+@enumerate
 
 @item
 Install @command{git-cl} by entering:
 
 @item
 Install @command{git-cl} by entering:
@@ -1064,11 +933,21 @@ symbolic link to the @command{git-cl} and @command{upload.py}
 scripts in one of your PATH directories (such as
 @file{$HOME/bin}).
 
 scripts in one of your PATH directories (such as
 @file{$HOME/bin}).
 
+@end enumerate
+
+@subsubheading @command{git-cl} configuration
+
+LilyDev users should perform these @q{configuration} instructions.
+
+@enumerate
+@item
+You must have a gmail account; please create one if you do not
+have one already.
 
 @item
 
 @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.  If you do not understand any
+question, just answer with a newline (CR).
 
 @example
 cd $HOME/lilypond-git/
 
 @example
 cd $HOME/lilypond-git/
@@ -1138,6 +1017,11 @@ 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.
 
 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
+set that includes a .scm file.  When this happens, it can
+generally be fixed by editing the file @file{/etc/mime.types}.
+Add a line to this file containing @code{text/x-script.scheme scm}.}
+
 @subsubheading Announcing your patch set
 
 You should then announce the patch by logging into the code review
 @subsubheading Announcing your patch set
 
 You should then announce the patch by logging into the code review
@@ -1145,6 +1029,9 @@ 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.
 
 (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
 @subsubheading Revisions
 
 As revisions are made in response to comments, successive patch sets