X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=Documentation%2Fcontributor%2Fsource-code.itexi;h=20077e6891c50a69bfc672b152f52b8a5a27e082;hb=739c7a7b6de031621341717c50f308dff51b2f88;hp=2567484e7075ab4627ad1ab8c51479d9a275ea4f;hpb=c872f352735c731958da165c83ea8598c5d58772;p=lilypond.git diff --git a/Documentation/contributor/source-code.itexi b/Documentation/contributor/source-code.itexi index 2567484e70..20077e6891 100644 --- a/Documentation/contributor/source-code.itexi +++ b/Documentation/contributor/source-code.itexi @@ -93,7 +93,7 @@ files. @end enumerate @warning{Throughout the rest of this manual, most command-line -input should be entered from @file{~/lilypond-git/}. This is +input should be entered from @file{$LILYPOND_GIT}. This is referred to as the @emph{top source directory}.} Further instructions are in @ref{How to use lily-git}. @@ -160,7 +160,7 @@ The above command will put the it in @file{~/lilypond-git}, where @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. @@ -171,7 +171,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 +repository being discussed (eg. @file{$LILYPOND_GIT}). This is referred to as the @emph{top source directory}.} Before working with the copy of the main LilyPond repository, you @@ -216,9 +216,9 @@ this to your @file{~/.bashrc}: 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. +You may need to install the additional @code{bash-completion} +package, but it is definitely worth it. After installation +you must log out, and then log back in again to enable it. @subsubheading Technical details @@ -531,7 +531,7 @@ We have a few other code repositories. @menu * lilypond-extra:: * Grand Unified Builder (GUB):: -* lilypad:: +* LilyPad:: * yet more repositories:: @end menu @@ -549,12 +549,22 @@ environment variable to point to that repository. @end example To configure an environment variable in bash (the default for most -Linux distributions), +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) @@ -577,16 +587,63 @@ and the original version by Jan Nieuwenhuizen, kept at @end example -@node lilypad -@unnumberedsubsubsec lilypad +@node LilyPad +@unnumberedsubsubsec LilyPad Our binary releases on MacOS X and Windows contain a lightweight -text editor. This code is here: +text editor. + +To make any modifications the Windows editor, you will need to do the +following: + +@enumerate +@item +Clone the git repository from @code{https://github.com/gperciva/lilypad} + +@item +Make changes to the source, and check it compiles. In a Windows environment +@code{MinGW} provides both a @code{Git} installation and a @code{gcc} +compiler. This can be obtained from @code{http://www.mingw.org/} + +@item +Update the version which is contained in the @file{rsrc.rc}. Check +this compiles, too. + +@item +Commit the changes with an informative commit message. + +@item +Push the changes to github. You will need to use syntax similiar to this: @example -https://github.com/gperciva/lilypad +git push https://UserName@@github.com/gperciva/lilypad.git @end example +You will need to have push access to the git repository for this to be +successful. + +@item +Make a tarball of the source code to be used by GUB by pulling the updated +repository from GitHub. Ensure that the tarball has the correct Version +number. + +@item +Copy the tarball to @code{http://lilypond.org/download/gub-sources/lilypad/}. +You will need to have SSH access to @code{lilypond.org}. If you do not, contact +the Release Manager via the lilypond-devel mailing list. + +@item +Update GUB to make it use the new tarball by editing +@file{gub/specs/lilypad.py} and changing the @code{source =} line to point to +the new source. + +@item +Push this updated @file{lilypad.py} version to the GUB repository on GitHub. + +@item +Test the changes with a new GUB compile. + +@end enumerate @node yet more repositories @unnumberedsubsubsec yet more repositories @@ -732,7 +789,7 @@ Already on 'master' @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}. @@ -1267,7 +1324,7 @@ 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 +In GNU/Linux you can add directories to PATH by adding this line to a hidden file @file{.bashrc}, located in your home directory: @@ -1283,32 +1340,48 @@ LilyDev users should perform these @q{configuration} instructions. @enumerate @item -You must have a google account; please create one if you do not +You must own a Google account login; 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. +@noindent +Note that a google account does not need to be a Gmail account; you can +use @emph{any} email address for your google account when you sign up. + +@warning{In order for @code{git-cl} to work as expected, your Google +Account Settings must have the @q{Access for less secure apps} set to +@q{Allowed}. This is normally the default setting.} @item 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). +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 +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.} @@ -1316,13 +1389,13 @@ There are two methods, depending on your git setup. @itemize @item -@strong{Master branch}: (easy option, and used in @command{lily-git.tcl}) +@strong{Master branch}: (easy option) 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? @@ -1340,13 +1413,25 @@ option. @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: +Ensure your changes are committed in a separate branch, which should +differ from the reference branch to be used (usually +@code{origin/master}) by just the changes to be uploaded. Checkout the +branch with the changes: + +@example +git checkout some-branch-with-changes +@end example + +If the reference branch is to be @code{origin/master}, ensure that the +branch containing the changes is up-to-date with it. Use +@command{git rebase} or @command{git pull -r} to rebase the branch to +the head of @code{origin/master}. For example: + +@example +git pull -r origin master +@end example + +Finally, start the upload by entering: @example git cl upload @@ -1366,6 +1451,11 @@ can be used. @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.