1 @c -*- coding: utf-8; mode: texinfo; -*-
3 @include included/helpus.itexi
5 @node Introduction to contributing
6 @chapter Introduction to contributing
8 This chapter presents a quick overview of ways that people can
13 * Overview of work flow::
14 * Summary for experienced developers::
29 @node Overview of work flow
30 @section Overview of work flow
32 @advanced{Experienced developers should skip to
33 @ref{Summary for experienced developers}.}
35 Git is a @emph{version control system} that tracks the history of
36 a program's source code. The LilyPond source code is maintained
37 as a Git repository, which contains:
41 all of the source files needed to build LilyPond, and
44 a record of the entire history of every change made to every file
45 since the program was born.
48 The @q{official} LilyPond Git repository is hosted by the GNU
49 Savannah software forge at @uref{http://git.sv.gnu.org}.
51 Changes made within one contributor's copy of the repository can
52 be shared with other contributors using @emph{patches}. A patch
53 is a text file that indicates what changes have been made.
54 If a contributor's patch is approved for inclusion (usually
55 through the mailing list), someone on the current development team
56 will @emph{push} the patch to the official repository.
58 The Savannah software forge provides two separate interfaces for
59 viewing the LilyPond Git repository online:
60 @uref{http://git.sv.gnu.org/cgit/lilypond.git/, cgit} and
61 @uref{http://git.sv.gnu.org/gitweb/?p=lilypond.git, gitweb}.
64 The cgit interface should work faster than gitweb
65 in most situations, but only gitweb allows you to search through
66 the source code using @command{grep}, which you may find useful.
69 Git is a complex and powerful tool, but tends to be confusing at
70 first, particularly for users not familiar with the command line
71 and/or version control systems. We have created the
72 @command{lily-git} graphical user interface to ease this
75 @emph{Compiling} (@q{building}) LilyPond allows developers to see
76 how changes to the source code affect the program itself.
77 Compiling is also needed to package the program for specific
78 operating systems or distributions. LilyPond can be compiled from
79 a local Git repository (for developers), or from a downloaded
80 tarball (for packagers). Compiling LilyPond is a rather involved
81 process, and most contributor tasks do not require it.
83 Contributors can contact the developers through the
84 @q{lilypond-devel} mailing list. The mailing list archive is
86 @uref{http://lists.gnu.org/archive/html/lilypond-devel/}. If you
87 have a question for the developers, search the archives first to
88 see if the issue has already been discussed. Otherwise, send an
89 email to @email{lilypond-devel@@gnu.org}. You can subscribe to
90 the developers' mailing list here:
91 @uref{http://lists.gnu.org/mailman/listinfo/lilypond-devel}.
93 @warning{Contributors on Windows or MacOS X wishing to compile
94 code or documentation are strongly advised to use our Debian
95 LilyPond Developer Remix, as discussed in @ref{Quick start}.}
98 @node Summary for experienced developers
99 @section Summary for experienced developers
101 If you are already familiar with typical open-source tools, here's
102 what you need to know:
105 @item @strong{source repository}:
106 hosted by GNU savannah.
109 @uref{http://git.savannah.gnu.org/gitweb/?p=lilypond.git}
112 @item @strong{environment variables}:
113 many maintenance scripts, and many instructions in this guide rely on
114 predefined @ref{Environment variables}.
116 @item @strong{mailing lists}:
117 given on @rweb{Contact}.
119 @item @strong{branches}:
123 base your work from this, but do @strong{not push} to it.
125 @item @code{staging}:
126 after a successful review (see below), push here.
128 @item @code{translation}:
129 translators should base their work from this, and also push to it.
131 @item @code{dev/foo}:
132 feel free to push any new branch name under @code{dev/}.
136 @item @strong{regression tests}:
137 also known as @qq{regtests}; this is a collection of more than a
138 thousand .ly files. We track the output of those files between
141 If a patch introduces any unintentional changes to the regtests,
142 we will likely reject it -- make sure that you are aware and can
143 explain any regtest changes. More info in @ref{Regression tests}.
145 @item @strong{reviews}:
146 after finishing work on a patch or branch:
150 upload it with our custom @code{git-cl}. In addition to uploading
151 it to the google rietveld code review tool, this adds a tracker
152 issue so that we don't lose your patch. The @qq{status} of your
153 patch is kept on the issue tracker; see @ref{Issues}.
156 @uref{https://github.com/gperciva/git-cl}
159 Your patch will be given @code{Patch-new} status. More info in
160 @ref{Uploading a patch for review}.
163 If your patch passes some automatic tests, it will be given
164 @code{Patch-review} status. This generally happens within 24
168 After that, the patch must wait for the next @qq{patch countdown},
169 which occur 3 times a week. If there are a lot of patches waiting
170 for a countdown, a subset of patches are chosen randomly. When
171 your patch is put on a countdown, it will be given
172 @code{Patch-countdown} status.
175 The countdown is a 48-hour period which gives other developers one
176 last chance to review the patch. If no significant problems are
177 found, your patch will be given @code{Patch-push} status.
180 You may now either push it to the @code{staging} branch, or email
181 your patch (created with @w{@code{git format-patch}}) to somebody
182 who will push it for you.
186 @advanced{Yes, this process means that most patches wait between
187 60-120 hours before reaching @code{master}. This is unfortunate, but
188 given our limited resources for reviewing patches and a history of
189 unintended breakage in @code{master}, this is the best compromise
192 @c I don't think this is important enough to list here, but I may
193 @c change my mind and/or leave a link to a later CG section.
195 @item @strong{code style}:
196 C++ code should be formatted with
197 @file{scripts/auxiliar/fixcc.py}, which requires
198 @url{http://astyle.sourceforge.net/, astyle 2.02}. However, we
199 are not very strict about this requirement.
201 At the moment, scheme code should be formatted @qq{like emacs does
202 it}. We are working on an automated tool to simplify this step.
203 However, we are not very strict about this requirement either.
212 We have a semi-formal system of mentorship, similar to the
213 medieval @qq{journeyman/master} training system. New contributors
214 will have a dedicated mentor to help them @qq{learn the ropes}.
216 @warning{This is subject to the availability of mentors; certain
217 jobs have more potential mentors than others.}
219 @subheading Contributor responsibilities
224 Ask your mentor which sections of the CG you should read.
227 If you get stuck for longer than 10 minutes, ask your mentor.
228 They might not be able to help you with all problems, but we find
229 that new contributors often get stuck with something that could be
230 solved/explained with 2 or 3 sentences from a mentor.
233 If you have been working on a task much longer than was originally
234 estimated, stop and ask your mentor. There may have been a
235 miscommunication, or there may be some time-saving tips that could
236 vastly simply your task.
239 Send patches to your mentor for initial comments.
242 Inform your mentor if you're going to be away for a month, or if
243 you leave entirely. Contributing to lilypond isn't for everybody;
244 just let your mentor know so that we can reassign that work to
248 Inform your mentor if you're willing to do more work -- we always
249 have way more work than we have helpers available. We try to
250 avoid overwhelming new contributors, so you'll be given less work
251 than we think you can handle.
256 @subheading Mentor responsibilities
261 Respond to questions from your contributor(s) promptly, even if
262 the response is just @qq{sorry, I don't know} or @qq{sorry, I'm
263 very busy for the next 3 days; I'll get back to you then}. Make
264 sure they feel valued.
267 Inform your contributor(s) about the expected turnaround for your
268 emails -- do you work on lilypond every day, or every weekend, or
269 what? Also, if you'll be unavailable for longer than usual (say,
270 if you normally reply within 24 hours, but you'll be at a
271 conference for a week), let your contributors know. Again, make
272 sure they feel valued, and that your silence (if they ask a
273 question during that period) isn't their fault.
276 Inform your contributor(s) if they need to do anything unusual for
277 the builds, such as doing a @qq{make clean / doc-clean} or
278 switching git branches (not expected, but just in case...)
281 You don't need to be able to completely approve patches. Make
282 sure the patch meets whatever you know of the guidelines (for doc
283 style, code indentation, whatever), and then send it on to -devel
284 for more comments. If you feel confident
285 about the patch, you can push it directly (this is mainly intended
286 for docs and translations; code patches should almost always go to
287 -devel before being pushed).
290 Keep track of patches from your contributor. Either upload them
291 to Rietveld yourself, or help+encourage them to upload the patches
292 themselves. When a patch is on Rietveld, it's your responbility
293 to get comments for it, and to add a link to the patch to the
294 google tracker. (tag it @qq{patch-new}, or @qq{patch-review} if
295 you feel very confident in it)
298 Encourage your contributor to review patches, particularly your
299 own! It doesn't matter if they're not familiar with C++ / scheme
300 / build system / doc stuff -- simply going through the process is
301 valuable. Besides, anybody can find a typo!
304 Contact your contributor at least once a week. The goal is just
305 to get a conversation started -- there's nothing wrong with simply
306 copy&pasting this into an email:
311 How are things going? If you sent a patch and got a review, do
312 you know what you need to fix? If you sent a patch but have no
313 reviews yet, do you know when you will get reviews? If you are
314 working on a patch, what step(s) are you working on?