X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=Documentation%2Fcontributor%2Fsource-code.itexi;h=7d3c04e2aecf49193edb73195903528ff3f4acf5;hb=2a6b3329c46ae620dbe80dfaef076b13c5344911;hp=97e1025e47bf9f9809207b6d847ab20a84fbd7a8;hpb=b5a72fde8d11be3bbcf2b78d98ece9e513c0de57;p=lilypond.git diff --git a/Documentation/contributor/source-code.itexi b/Documentation/contributor/source-code.itexi index 97e1025e47..7d3c04e2ae 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 @@ -372,7 +372,7 @@ At this stage, don't worry about how many commits you have. 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 chages first. +commit your changes first. @example git commit -a @@ -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,39 +549,101 @@ 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) Another item of interest might be the Grand Unified Builder, our -cross-platform building tool. Since it is used by projects as +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, which will hopefully -be kept up-to-date with each other: +There are two locations for this repository: the version being used to +build lilypond, which is at @example -@uref{http://github.com/janneke/gub} @uref{http://github.com/gperciva/gub} @end example +and the original version by Jan Nieuwenhuizen, kept at -@node lilypad -@unnumberedsubsubsec lilypad +@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: +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 @@ -623,7 +685,7 @@ 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{translation} branch after significant changes to the English documentation. See @@ -727,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}. @@ -1019,12 +1081,11 @@ git merge @var{foo} 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{translation}; on the other hand, the Translations -meister wants to merge @code{translation} into -@code{master} whenever he has checked that -@code{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 @@ -1263,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: @@ -1279,32 +1340,52 @@ 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: + +@item +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 +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.} @@ -1318,9 +1399,10 @@ 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? 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. @@ -1361,6 +1443,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. @@ -2039,6 +2126,15 @@ 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