X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=Documentation%2Fcontributor%2Fintroduction.itexi;h=c104cee17551acb2790d8a512c9bb84a1d5e63ec;hb=512542520ca60b7018df2de43e2c5f51bf05432c;hp=f91af57f7949f6b6aa1f2c91d5a8766ad52e53e2;hpb=89c79016c99ca97ee8fcb720c1128f1a0336eaf6;p=lilypond.git diff --git a/Documentation/contributor/introduction.itexi b/Documentation/contributor/introduction.itexi index f91af57f79..c104cee175 100644 --- a/Documentation/contributor/introduction.itexi +++ b/Documentation/contributor/introduction.itexi @@ -1,48 +1,43 @@ -@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:: +* 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: +@helpusProjects -@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{lilypond-devel@gnu.org} for -discussion. +@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 -@node For other contributors -@section For other contributors - - -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 +50,136 @@ 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. We have created the +@command{lily-git} graphical user interface to ease this +difficulty. + +@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 lilybuntu, as +discussed in @ref{Quick start}.} + + +@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 +