CG: Update info - how to request access to tracker

[lilypond.git] / Documentation / contributor / quick-start.itexi

@c -*- coding: utf-8; mode: texinfo; -*-

@node Quick start
@chapter Quick start

Want to submit a patch for LilyPond?  Great!  Never created a patch
before? Never compiled software before? No problem!  This chapter is
for you and will help you do this as quickly and easily as possible.

@menu
* LilyDev::
* lily-git::
* git-cl::
* Compiling with LilyDev::
* Now start work!::
@end menu

@node LilyDev
@section LilyDev

@c This text was written based on LilyDev 4.0 - JL

There is a @q{remix} of Debian GNU/Linux -- known as @qq{LilyDev} for
short -- which includes all the necessary software and tools to compile
LilyPond, the documentation and the website (also see
@ref{Website work}).

@warning{LilyDev does not include the software for the Grand Unified
Builder -- also see @ref{Grand Unified Builder (GUB)}.}

While compiling LilyPond on Mac OS and Windows is possible, both
environments are complex to set up.  LilyDev can be easily installed
and run inside a @q{virtual machine} on either of these operating
systems relatively easily using readily available virtualization
software.  We recommend using VirtualBox as it is available for all
major operating systems and is very easy to install & configure.

The LilyDev disk image can also be written to a USB device or @q{burnt}
to a DVD -- it is approximately 900 MB in size -- and installed just
like any standard GNU/Linux distribution.

The current image is based on a 32-bit version of Debian 8 (@q{Jessie})
and the disk image was generated using Debian
@uref{http://live.debian.net/, live-build 4}.

@noindent
Download the LilyDev disk image file (a @code{.iso} file) from here:

@example
@uref{https://github.com/fedelibre/LilyDev/releases/latest}
@end example

@warning{Apart from installing and configuring LilyDev in VirtualBox,
the rest of the chapter assumes that you are comfortable using the
command-line and is intended for users who may have never created a
patch or compiled software before.  More experienced developers (who
prefer to use their own development environment) may still find it
instructive to skim over the following information.}

If you are not familiar with GNU/Linux, it may be beneficial to read a
few @qq{introduction to Linux} type web pages.

@menu
* Installing LilyDev in VirtualBox::
* Configuring LilyDev in VirtualBox::
@end menu


@node Installing LilyDev in VirtualBox
@unnumberedsubsec Installing LilyDev in VirtualBox

This section discusses how to install and use LilyDev with VirtualBox.

@warning{If you already know how to install a virtual machine using a
disc image inside VirtualBox (or your own virtualization software) then
you can skip this section and go straight to @ref{lily-git}.}

@enumerate
@item
Download VirtualBox from here:

@example
@uref{http://www.virtualbox.org/wiki/Downloads}
@end example

@warning{In virtualization terminology, the operating system where
VirtualBox is installed is known as the @strong{host}.  LilyDev
will be installed @q{inside} VirtualBox as a @strong{guest}.}

@item
Start the VirtualBox software and click @q{New} to create a new
@qq{virtual machine}.

The @q{New Virtual Machine Wizard} will walk you through setting up your
guest virtual machine.  Choose an appropriate name for your LilyDev
installation and select the @q{Linux} operating system.  When selecting
the @q{version} choose @q{Debian (32 bit)} (don't use the @q{64 bit}
option).  If you do not have that specific option choose @q{Linux 2.6}
(again do not choose any option that has 64 bit next to it).

@item
Select the amount of RAM you will allow the LilyDev guest to use from
your host operating system when it is running.  If possible, use at
least 700 MB of RAM; the more RAM you can spare from your host the
better, although LilyDev will currently use no more than 4 GB (4096 MB)
even if you are able to assign more.

@item
For your @q{Virtual Hard Disk}, leave the @q{Create new hard disk}
option checked, use the default @q{VDI} and @qq{Dynamically allocated}
options for the virtual hard drive.  A complete compile of everything
(code, docs, regression tests) can reach 10 GB so size your virtual disk
and its location accordingly.

@item
Verify the summary details and click @q{Create}, when you are satisfied.
Your new guest will be displayed in the VirtualBox window.

@warning{The image contains a @q{686-pae} kernel, so you must enable
@code{PAE} within the virtual machine's settings -- click on
@clicksequence{System @click{} Processor} and select
@q{Extended features: Enable PAE/NX}.}

@item
Click the @q{Start} button and the @q{First Run Wizard} will prompt you
for the installation media.  Click the browse icon, locate the LilyDev
disk image file that you downloaded (the @code{.iso} file) and click
through the wizard to begin the installation process.

@item
When the LilyDev disk image boots for the first time, choose either the
@q{Install} or the @q{Graphical install} menu item.  The installer will
then walk you through the complete installation process.

@item
At the @qq{Partition disks} stage, do not be afraid to select
@qq{Guided - use entire disk}, since this refers to your
@strong{@emph{virtual disk}}, not your computer's own hard disk.

@item
Continue to click through the rest of the wizard, filling in any
appropriate details when asked, and wait for the install to complete.
This will take about 10 minutes or so on a reasonably modern computer.

@item
When the installation is completed, just click on @q{Continue} (you
do not have to remove any media since you installed LilyDev from a Disk
image, which is just a file on your computer).  The installer will
reboot the virtual machine.

@end enumerate

@noindent
LilyDev should now be installed and running!


@node Configuring LilyDev in VirtualBox
@unnumberedsubsec Configuring LilyDev in VirtualBox

VirtualBox has extra @q{guest additions} which although are not
necessary to use LilyDev or compile LilyPond, do provide some additional
features to your Virtual Machine to make it easier to work with.  Such
as being able to dynamically resize the LilyDev window, allow seamless
interaction with your mouse pointer on both the host and guest and let
you copy/paste between your host and guest if needed.

@enumerate

@item
Select the @q{Devices} menu from the virtual machine window and choose
@q{Install Guest Additions...}.  This will automount a CD which will
prompt you to autorun it.  Click OK and follow the instructions.  It is
recommended to reboot the guest when the installation is complete.

Other virtualization software will also have their own @q{guest}
additions, follow the normal procedures for your virtualization software
with LilyDev as the client.

@item
Restart LilyDev to complete the installation of the guest additions.

@advanced{If you do any kernel upgrades, you may need to reinstall the
additional software.  Just follow the step above again and reboot when
the reinstallation is complete.}

@end enumerate

@noindent
Other items that may be helpful:

@itemize

@item
In the settings for the virtual machine, set the network to
Bridged mode to allow you to access shared folders when using Windows
hosts.

@item
Set up any additional features, such as @q{Shared Folders} between
your main operating system and LilyDev.  This is distinct from the
networked share folders in Windows.  Consult the external documentation
for this.

Some longtime contributors have reported that @q{shared folders}
are rarely useful and not worth the fuss, particularly since files
can be shared over a network instead.

@item
Pasting into a terminal is done with @code{Ctrl+Shift+v}.

@item
Right-click allows you to edit a file with the text editor (default
is Leafpad).

@end itemize

@knownissues
Not all hardware is supported in all virtualization tools.  In
particular, some contributors have reported problems with USB network
adapters.  If you have problems with network connection (for example
Internet connection in the host system is lost when you launch virtual
system), try installing and running LilyDev with your computer's
built-in network adapter used to connect to the network.  Refer to the
help documentation that comes with your virtualization software.


@node lily-git
@section lily-git

The @q{LilyPond Contributor's Git Interface} (otherwise known as
@command{lily-git.tcl}) is a simple-to-use GUI to help you download and
update the LilyPond source code as well as an aid to making software
patches.

@menu
* Where to get lily-git::
* Using lily-git to download the source code::
* How to use lily-git::
@end menu

@node Where to get lily-git
@unnumberedsubsec Where to get lily-git

Depending on your development environment, lily-git may already be
installed on your computer.

@itemize
@item
If you are using LilyDev (see @ref{LilyDev}) then lily-git should
already be installed and ready to run.  If this is not the case you can
easily turn it on by adding the following line in @code{~/.bashrc}:

@example
# add lily-git to the PATH
PATH=$LILYPOND_GIT/scripts/auxiliar:"$@{PATH@}"
@end example

@item
For those not using LilyDev, lily-git can be obtained by downloading
the software directly. See @ref{Manually installing lily-git.tcl}.

@item
lily-git is part of the LilyPond source code and is located in
@file{$LILYPOND_GIT/scripts/auxillar/lily-git.tcl}.

@end itemize


@node Using lily-git to download the source code
@unnumberedsubsec Using lily-git to download the source code

@enumerate
@item
Type the following command into a Terminal:

@example
lily-git.tcl
@end example

@noindent
You will be prompted to enter a name and email address into the lily-git
UI.  This information is used to label any patches you create (using the
lily-git UI or git via the command line) and can be changed later if
required.  See @ref{Configuring Git}.

@item
Click on the @emph{Submit} button to update lily-git with the
information.

@item
Click on the @qq{Get source} button.

A directory called @file{lilypond-git} is created within your home
directory and the entire source code will start to be downloaded into
it.

@warning{Be patient! There is no progress bar in the lily-git UI but the
complete source is around 180@tie{}MB.}

@noindent
When the source code has been downloaded, the @qq{command output} window
in the lily-git UI will update and display @qq{Done} on the very last
line and the button label will change to say @qq{Update source}.

@warning{Some contributors have reported that occasionally nothing
happens at this step at all.  If this occurs, then try again in a few
minutes -- it could be an intermittant network problem.  If the
problem persists, please ask for help.}

@item
Close the lily-git GUI and navigate to the @file{lilypond-git}
directory to view and edit the source files.

@end enumerate

@noindent
If this is the first time you will be attempting to compile LilyPond,
please see the section @ref{Compiling with LilyDev} before continuing.


@node How to use lily-git
@unnumberedsubsec How to use lily-git

Here is a brief description of what each button does in the lily-git UI.

@advanced{Throughout the rest of this manual, most command-line
input should be entered from within the top level of the
@file{~/lilypond-git/} directory.  This is known as the
@emph{top of the source directory} and is also referred to as
@var{$LILYPOND_GIT} as a convention for those users who may have
configured their own locations of the LilyPond source code.}

@warning{For those less experienced contributors using lily-git, we
recommend that you only work on one set of changes at a time and not
start on any new changes until your first set has been accepted.}

@subsubheading 1. Update source

Click the @qq{Update source} button to get any recent changes to the
source code that have been added by other contributors since your last
session.

@warning{If another contributor has updated files in the source code
that you had been working on then updating your own copy of the source
code may result in what is known as a @emph{merge conflict}.  If this
occurs, follow the instructions to @qq{Abort changes}, below.  Note that
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}.}


@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
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}.

@item
If you have trouble uploading the patch for review,
ask for help on @email{lilypond-devel@@gnu.org}.

@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 git-cl
@section git-cl

@menu
* Installing git-cl::
* Updating git-cl::
* Configuring git-cl::
@end menu

Git-cl is a @q{helper script} that uploads patches to Google's Rietveld
Code Review Tool -- used by the developers for patch review -- and, at
the same time, updates LilyPond's issue tracker.


@node Installing git-cl
@unnumberedsubsec Installing @code{git-cl}

@warning{LilyDev users can jump straight to the next section on updating
@command{git-cl} as it will already be installed in your home
directory.}

@enumerate

@item
Download @command{git-cl} by running the command:

@example
git clone https://github.com/gperciva/git-cl.git
@end example

@noindent
or, if that command fails for any reason, try:

@example
git clone git://github.com/gperciva/git-cl.git
@end example

@item
Add the @file{git-cl/} directory to your @var{PATH} or create a symbolic
link to the @command{git-cl} and @command{upload.py} scripts in one of
your @var{PATH} directories (e.g. @file{$HOME/bin}).

In GNU/Linux you can add directories to @var{PATH} by adding this line
to your @file{.bashrc} file located in your home directory:

@example
PATH=~/directory_containing_git-cl:"$@{PATH@}"
@end example

@end enumerate


@node Updating git-cl
@unnumberedsubsec Updating @code{git-cl}

LilyDev users should make sure that they always have the latest
version of git-cl installed.  It is possible that changes have been
made to git-cl that are not (yet) included in the version of LilyDev
that you are using.

@noindent
Using a terminal run the following commands:

@example
cd ~/git-cl/
git pull
@end example

This will download and update you to the lastest version of git-cl.


@node Configuring git-cl
@unnumberedsubsec Configuring @code{git-cl}

Because @code{git-cl} updates two separate websites (Google's Rietveld
Code Review Tool and LilyPond's issue tracker) you @emph{must} have a
valid user account (login and password) for both sites.

@subsubheading Set up a login account for Rietveld Code Review Tool

@noindent
For the Rietveld Code Review Tool you will need a Google account but
this does @emph{not} require @q{Google} email address; i.e. @emph{any}
email address for your Google account can be used.  Just select the
option @qq{I prefer to use my current email address} when you sign up
with Google.

@warning{In order for @code{git-cl} to work correctly with this Google
account, your Google Account Settings must have the
@q{Access for less secure apps} set to @q{Allowed} -- this is normally
the default setting.}

@subsubheading Set up a login account for LilyPond's Issue Tracker

@noindent
Please register a user account at
@code{https://sourceforge.net/user/registration} preferably using the
same email address that you want to use LilyPond Developer mailing list
login.

@noindent
Once you have created this Sourceforge user account, send an email to
the LilyPond Developer's mailing list (@code{lilypond-devel@@gnu.org})
asking for write access to the issue tracker along with your Sourceforce
@emph{Username} (not email address) and someone will then be able to set
this up for you.

@subsubheading Authorizing git-cl for the LilyPond issue tracker

The @code{git-cl} command itself also needs to be @q{authorized} so that
it can access the LilyPond issue tracker.

@enumerate
@item
Once you have been given a valid login for the LilyPond issue tracker,
go to the @q{Account settings} and select the @q{OAuth} tab.

@item
Locate the @q{Register New Application} section and enter @code{git-cl}
in the @q{Application Name:} field.

@item
Click on the @q{Register new application} button.  You should now see
@q{git-cl} listed under the @q{My Applications} section.

@item
Click on the @q{Generate Bearer Token} button.  You should now see
@q{git-cl} listed under the @q{Authorized Applications} section along
with a value for the @q{Bearer Token} entry.  This value is used, in the
next steps, to allow git-cl to access and update the LilyPond issue
tracker.

@end enumerate

@subsubheading Installing ca-certificates

In order to have @code{git-cl} properly update issues on the SourceForge
Allura issue tracker, you must have the package @code{ca-certificates}
installed.  You can check to see if the package is installed with

@example
apt --installed list | grep ca-certificates
@end example

If @code{ca-certificates} is installed, you will get a result that shows
the version that is installed.  If it is not installed, there will be
no version displayed.

Install @code{ca-certificates} with the following:

@example
sudo apt-get install ca-certificates
@end example


@subsubheading Running git-cl for the first time

@enumerate
@item
Using a terminal, move to the top level of the @code{$LILYPOND_GIT}
directory and then run @code{git-cl} with the @code{config} option:

@example
cd $LILYPOND_GIT
git-cl config
@end example

@noindent
You will see a series of prompts.  For most of them you can simply
accept the default value by responding with a newline (i.e. by pressing
return or enter).

@item
The prompt for the @code{Rietveld server} (the patch review tool), which
defaults to @code{codereview.appspot.com}

@example
Rietveld server (host[:port]) [codereview.appspot.com]:
@end example

@item
The prompt for the @code{Allura server} (the issue tracker), which
defaults to @code{https://sourceforge.net/p/testlilyissues/issues/}

@example
Allura server [https://sourceforge.net/p/testlilyissues/issues/]:
@end example

@item
When prompted for the @code{Allura bearer token} copy/paste the value
generated in the previous steps for
@emph{Authorising git-cl for the LilyPond issue tracker}

@smallexample
Allura bearer token (see https://sourceforge.net/auth/oauth/): fdbfca60801533465480
@end smallexample

@warning{The above is a @q{fake} bearer token used just for
illustration. Do not use this value.}

@item
Finally, the prompt for the @code{CC list}, which defaults to
@code{lilypond-devel@@gnu.org}, the LilyPond Developer's email list.

@example
CC list ("x" to clear) [lilypond-devel@@gnu.org]:
@end example

@end enumerate

The @code{git-cl} script should now be correctly configured for use.


@node Compiling with LilyDev
@section Compiling with LilyDev

LilyDev is our @q{remix} of Debian which contains all the
necessary dependencies to do LilyPond development; for more
information, see @ref{LilyDev}.

@subsubheading Preparing the build

To prepare the build directory, enter (or copy&paste) the below
text.  This should take less than a minute.

@c we heavily recommend the out-of-tree build; do not change this!

@example
cd $LILYPOND_GIT
sh autogen.sh --noconfigure
mkdir -p build/
cd build/
../configure
@end example

@subsubheading Building @code{lilypond}

Compiling LilyPond will take anywhere between 1 and 15 minutes on most
@q{modern} computers -- depending on CPU and available RAM.  We also
recommend that you minimize the terminal window while it is building;
this can help speed up on compilation times.

@example
cd $LILYPOND_GIT/build/
make
@end example

@noindent
It is possible to run @code{make} with the @code{-j} option to help
speed up compilation times even more.  See @ref{Compiling LilyPond}

You may run the compiled @code{lilypond} with:

@example
cd $LILYPOND_GIT/build/
out/bin/lilypond my-file.ly
@end example

@subsubheading Building the documentation

Compiling the documentation is a much more involved process, and
will likely take 2 to 10 hours.

@example
cd $LILYPOND_GIT/build/
make
make doc
@end example

The documentation is put in @file{out-www/offline-root/}.  You may
view the html files by entering the below text; we recommend that
you bookmark the resulting page:

@example
firefox $LILYPOND_GIT/build/out-www/offline-root/index.html
@end example

@subsubheading Installing

Don't.  There is no reason to install LilyPond within LilyDev.
All development work can (and should) stay within the
@file{$LILYPOND_GIT} directory, and any personal composition
or typesetting work should be done with an official GUB release.


@subsubheading Problems and other options

To select different build options, or isolate certain parts of the
build, or to use multiple CPUs while building, read
@ref{Compiling}.

In particular, contributors working on the documentation should be
aware of some bugs in the build system, and should read the
workarounds in @ref{Generating documentation}.


@node Now start work!
@section Now start work!

LilyDev users may now skip to the chapter which is aimed at
their intended contributions:

@itemize
@item @ref{Documentation work}
@item @ref{Translating the documentation}
@item @ref{Website work}
@item @ref{Regression tests}
@item @ref{Programming work}
@end itemize

These chapters are mainly intended for people not using LilyDev,
but they contain extra information about the
@qq{behind-the-scenes} activities.  We recommend that you read
these at your leisure, a few weeks after beginning work with
LilyDev.

@itemize
@item @ref{Working with source code}
@item @ref{Compiling}
@end itemize