X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=Documentation%2Fcontributor%2Fintroduction.itexi;h=167579bc9271890e89297219eeb70816a0f307d4;hb=b49d202431e10109e9130f34e101345d5ca16f55;hp=a5bb2eab09f03f08a1d2a0da6b6af99c0c288c5a;hpb=16937e6e8d61de2309ec7272ef768f6a0cfb4b12;p=lilypond.git diff --git a/Documentation/contributor/introduction.itexi b/Documentation/contributor/introduction.itexi index a5bb2eab09..167579bc92 100644 --- a/Documentation/contributor/introduction.itexi +++ b/Documentation/contributor/introduction.itexi @@ -1,48 +1,44 @@ -@c -*- coding: us-ascii; mode: texinfo; -*- +@c -*- coding: utf-8; mode: texinfo; -*- + +@include included/helpus.itexi @node Introduction to contributing @chapter Introduction to contributing +This chapter presents a quick overview of ways that people can +help LilyPond. @menu -* Overview of tasks:: -* For unix developers:: -* For other contributors:: +* Help us:: +* Overview of work flow:: +* Lilybuntu:: +* Mentors:: @end menu -@node Overview of tasks -@section Overview of tasks - - -FIXME: The intro should contain the "help us" material from web/, -quite possibly as the very first thing. This requires having a -macro for it, which depends on issue 939. - +@node Help us +@section Help us -@node For unix developers -@section For unix developers +@helpusNeed +@helpusTasks -To download the LilyPond Git repository: - -@example -git clone git://git.sv.gnu.org/lilypond.git -@end example - -Documentation is built using Texinfo. Subscribe to the -developers' mailing list at -@uref{http://lists.gnu.org/mailman/listinfo/lilypond-devel} and -send well-formed Git patches to @uref{mailto:lilypond-devel@@gnu.org} for -discussion. +@helpusProjects -@node For other contributors -@section For other contributors +@node Overview of work flow +@section Overview of work flow +@cartouche +@strong{Ultra-short summary for Unix developers}: source code is at +@code{git://git.sv.gnu.org/lilypond.git}. Documentation is built +with Texinfo, after pre-processing with @code{lilypond-book}. +Send well-formed patches to @email{lilypond-devel@@gnu.org}. +@end cartouche -The LilyPond source code is maintained as a Git repository, which -contains: +Git is a @emph{version control system} that tracks the history of +a program's source code. The LilyPond source code is maintained +as a Git repository, which contains: @itemize @item @@ -55,24 +51,274 @@ since the program was born. The @q{official} LilyPond Git repository is hosted by the GNU Savannah software forge at @uref{http://git.sv.gnu.org}. -Although, since Git uses a @q{distributed} model, technically +Although, since Git uses a @emph{distributed} model, technically there is no central repository. Instead, each contributor keeps a complete copy of the entire repository (about 116M). Changes made within one contributor's copy of the repository can be shared with other contributors using @emph{patches}. A patch -is a simple text file generated by the @code{git} program that +is a simple text file generated by the @command{git} program that indicates what changes have been made (using a special format). If a contributor's patch is approved for inclusion (usually through the mailing list), someone on the current development team -will @emph{apply} (or @q{push}) the patch to the official -repository. - -Compiling (@q{building}) LilyPond allows developers to see how -changes to the source code affect the program itself. Compiling -is also needed to package the program for specific operating -systems or distributions. LilyPond can be compiled from a local -Git repository (for developers), or from a downloaded tarball (for -packagers). Compiling LilyPond is a rather involved process, and -most contributor tasks do not require it. +will @emph{push} the patch to the official repository. + +The Savannah software forge provides two separate interfaces for +viewing the LilyPond Git repository online: @emph{cgit} and +@emph{gitweb}. The cgit interface should work faster than gitweb +in most situations, but only gitweb allows you to search through +the source code using @command{grep}, which you may find useful. +The cgit interface is at +@uref{http://git.sv.gnu.org/cgit/lilypond.git/} and the gitweb +interface is at +@uref{http://git.sv.gnu.org/gitweb/?p=lilypond.git}. + +Git is a complex and powerful tool, but tends to be confusing at +first, particularly for users not familiar with the command line +and/or version control systems. Contributors who don't want to +deal with Git directly are encouraged to use the +@command{lily-git} graphical user interface instead. + +@emph{Compiling} (@q{building}) LilyPond allows developers to see +how changes to the source code affect the program itself. +Compiling is also needed to package the program for specific +operating systems or distributions. LilyPond can be compiled from +a local Git repository (for developers), or from a downloaded +tarball (for packagers). Compiling LilyPond is a rather involved +process, and most contributor tasks do not require it. + +Contributors can contact the developers through the +@q{lilypond-devel} mailing list. The mailing list archive is +located at +@uref{http://lists.gnu.org/archive/html/lilypond-devel/}. If you +have a question for the developers, search the archives first to +see if the issue has already been discussed. Otherwise, send an +email to @email{lilypond-devel@@gnu.org}. You can subscribe to +the developers' mailing list here: +@uref{http://lists.gnu.org/mailman/listinfo/lilypond-devel}. + +@warning{Contributors on Windows or MacOS X wishing to compile +code or documentation are strongly advised to use @ref{Lilybuntu} +instead of trying to install all software dependencies +themselves.} + + +@node Lilybuntu +@section Lilybuntu + +It is not possible to compile LilyPond on Windows, and extremely +difficulty to compile it on MacOS X. We have therefore made a +@q{remix} of Ubuntu which includes all necessary dependencies to +compile both LilyPond and the documentation. This can be run +inside a virtual machine without disturbing your main operating +system. + +@enumerate +@item +Install some virtualization software. + +Any virtualization tool can be used, but we recommend VirtualBox: + +@example +@uref{http://@/www.virtualbox.org/@/wiki/@/Downloads} +@end example + +In virtualization terminology, your main operating system is the +@qq{host}. + +@item +Download the @file{lilybuntu2.iso} disk image: + +@example +@uref{http://files.lilynet.net/lilybuntu2.iso} +@end example + +@advanced{There is a md5sum available: +@uref{http://files.lilynet.net/lilybuntu2.iso.md5}} + +@item +Install @file{lilybuntu2.iso} as the @qq{guest} operating system +on your virtualized system. + +@itemize + +@item +If possible, use at least 700 MB of RAM (1GB would be better) for +the virtual machine, and use @qq{dynamically expanding storage} +for the virtual hard drive. A complete compile of everything +(code, docs, regression tests) can reach 10 GB. + +@item +When @file{lilybuntu2.iso} boots, it shows an ISOLINUX +@code{boot:} prompt. Type: + +@example +install +@end example + +@item +At the @qq{Prepare disk space} stage, do not be afraid to select +@qq{Erase and use the entire disk}, since this refers to your +@emph{virtual disk}, not your machine's actual hard drive. + +@item +After restarting your system, if you see the ISOLINUX @code{boot:} +prompt again, go to +@w{Devices@arrow{}CD/DVD Devices@arrow{}} and @emph{de-select} +the @q{lilybuntu2.iso} option, then reboot. + +@end itemize + +@advanced{ +The latest version of lilybuntu is based on Ubuntu 10.04.1; if you +encounter any difficulties installing it, search for one of the +many tutorials for installing that particular version of Ubuntu as +a client operating system. +} + +@item +Do any extra configuration for your virtualization software. + +VirtualBox has extra @qq{guest additions} which can make the +virtualization easier to use (full-screen, easy file sharing +between host and client operating systems, shared clipboards, +etc). + +@enumerate + +@item +From the @code{Devices} menu of VirtualBox, select @code{Install +Guest Additions...}. + +@item +From the @code{Places} menu of Ubuntu, select +@code{VBOXADDITIONS_}. A file-system window will open. + +@item +Double-click on the @file{autorun.sh} file, then select @qq{Run in +Terminal}, and enter your password when prompted. + +@item +Once the script is finished, reboot your Virtual Machine to +complete the installation. + +@advanced{If you do any kernel upgrades, you may need to re-run +these VBOXADDITIONS instructions.} + +@end enumerate + +If you use other virutalization software, then follow the normal +procedures for your virtualization software with Ubuntu as the +client. + +@advanced{not all hardware is supported in all virtualization +tools. In particular, some contributors have reported problems +with USB devices. If you would like to investigate further, then +look for help for your virtualization tool using your normal OS as +the @qq{host} and Ubuntu as the @qq{client}.} + +@end enumerate + +If you are not familiar with Linux, it may be beneficial to read a +couple of @qq{introduction to Ubuntu} webpages. + +@itemize +@item +One particular change from Windows and MacOS X is that most +software should be installed with your @qq{package manager}; this +vastly simplifies the process of installing and configuring +software. Go to +@w{System@arrow{}Administration@arrow{}Synaptic Package Manager}. + +@item +The rest of this manual assumes that you are using the +command-line; go to +@w{Applications@arrow{}Accessories@arrow{}Terminal}. + +@end itemize + +You should now progress to @ref{Using lily-git}. + + +@node Mentors +@section Mentors + +We have a semi-formal system of mentorship, similar to the +medieval @qq{journeyman/master} training system. New contributors +will have a dedicated mentor to help them @qq{learn the ropes}. + +@warning{This is subject to the availability of mentors; certain +jobs have more potential mentors than others.} + +@subheading Contributor responsibilities + +@enumerate + +@item +Ask your mentor which sections of the CG you should read. + +@item +If you get stuck for longer than 10 minutes, ask your mentor. +They might not be able to help you with all problems, but we find +that new contributors often get stuck with something that could be +solved/explained with 2 or 3 sentences from a mentor. + +@item +Send patches to your mentor for initial comments. + +@item +Inform your mentor if you're going to be away for a month, or if +you leave entirely. Contributing to lilypond isn't for everybody; +just let your mentor know so that we can reassign that work to +somebody else. + +@item +Inform your mentor if you're willing to do more work -- we always +have way more work than we have helpers available. We try to +avoid overwhelming new contributors, so you'll be given less work +than we think you can handle. + +@end enumerate + + +@subheading Mentor responsibilities + +@enumerate + +@item +Respond to questions from your contributor(s) promptly, even if +the response is just @qq{sorry, I don't know} or @qq{sorry, I'm +very busy for the next 3 days; I'll get back to you then}. Make +sure they feel valued. + +@item +Inform your contributor(s) about the expected turnaround for your +emails -- do you work on lilypond every day, or every weekend, or +what? Also, if you'll be unavailable for longer than usual (say, +if you normally reply within 24 hours, but you'll be at a +conference for a week), let your contributors know. Again, make +sure they feel valued, and that your silence (if they ask a +question during that period) isn't their fault. + +@item +Inform your contributor(s) if they need to do anything unusual for +the builds, such as doing a @qq{make clean / doc-clean} or +switching git branches (not expected, but just in case...) + +@item +You don't need to be able to completely approve patches. Make +sure the patch meets whatever you know of the guidelines (for doc +style, code indentation, whatever), and then send it on to the +frog list or -devel for more comments. If you feel confident +about the patch, you can push it directly (this is mainly intended +for docs and translations; code patches should almost always go to +-devel before being pushed). + +@item +Keep track of patches from your contributor. If you've sent a +patch to -devel, it's your responsibility to pester people to get +comments for it, or at very least add it to the google tracker. + +@end enumerate +