]> git.donarmstrong.com Git - lilypond.git/blob - Documentation/contributor/introduction.itexi
Issue 3420: Stop Documentation/ly-examples/orchestra.ly from redefining markup commands
[lilypond.git] / Documentation / contributor / introduction.itexi
1 @c -*- coding: utf-8; mode: texinfo; -*-
2
3 @include included/helpus.itexi
4
5 @node Introduction to contributing
6 @chapter Introduction to contributing
7
8 This chapter presents a quick overview of ways that people can
9 help LilyPond.
10
11 @menu
12 * Help us::
13 * Overview of work flow::
14 * Summary for experienced developers::
15 * Mentors::
16 @end menu
17
18
19 @node Help us
20 @section Help us
21
22 @helpusNeed
23
24 @helpusSimple
25
26 @helpusAdvanced
27
28
29 @node Overview of work flow
30 @section Overview of work flow
31
32 @advanced{Experienced developers should skip to
33 @ref{Summary for experienced developers}.}
34
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:
38
39 @itemize
40 @item
41 all of the source files needed to build LilyPond, and
42
43 @item
44 a record of the entire history of every change made to every file
45 since the program was born.
46 @end itemize
47
48 The @q{official} LilyPond Git repository is hosted by the GNU
49 Savannah software forge at @uref{http://git.sv.gnu.org}.
50 Although, since Git uses a @emph{distributed} model, technically
51 there is no central repository.  Instead, each contributor keeps a
52 complete copy of the entire repository (about 116MB).
53
54 Changes made within one contributor's copy of the repository can
55 be shared with other contributors using @emph{patches}.  A patch
56 is a simple text file generated by the @command{git} program that
57 indicates what changes have been made (using a special format).
58 If a contributor's patch is approved for inclusion (usually
59 through the mailing list), someone on the current development team
60 will @emph{push} the patch to the official repository.
61
62 The Savannah software forge provides two separate interfaces for
63 viewing the LilyPond Git repository online: @emph{cgit} and
64 @emph{gitweb}.  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.
67 The cgit interface is at
68 @uref{http://git.sv.gnu.org/cgit/lilypond.git/} and the gitweb
69 interface is at
70 @uref{http://git.sv.gnu.org/gitweb/?p=lilypond.git}.
71
72 Git is a complex and powerful tool, but tends to be confusing at
73 first, particularly for users not familiar with the command line
74 and/or version control systems.  We have created the
75 @command{lily-git} graphical user interface to ease this
76 difficulty.
77
78 @emph{Compiling} (@q{building}) LilyPond allows developers to see
79 how changes to the source code affect the program itself.
80 Compiling is also needed to package the program for specific
81 operating systems or distributions.  LilyPond can be compiled from
82 a local Git repository (for developers), or from a downloaded
83 tarball (for packagers).  Compiling LilyPond is a rather involved
84 process, and most contributor tasks do not require it.
85
86 Contributors can contact the developers through the
87 @q{lilypond-devel} mailing list.  The mailing list archive is
88 located at
89 @uref{http://lists.gnu.org/archive/html/lilypond-devel/}.  If you
90 have a question for the developers, search the archives first to
91 see if the issue has already been discussed.  Otherwise, send an
92 email to @email{lilypond-devel@@gnu.org}.  You can subscribe to
93 the developers' mailing list here:
94 @uref{http://lists.gnu.org/mailman/listinfo/lilypond-devel}.
95
96 @warning{Contributors on Windows or MacOS X wishing to compile
97 code or documentation are strongly advised to use our Ubuntu
98 LilyPond Developer Remix, as discussed in @ref{Quick start}.}
99
100
101 @node Summary for experienced developers
102 @section Summary for experienced developers
103
104 If you are already familiar with typical open-source tools, here's
105 what you need to know:
106
107 @itemize
108 @item @strong{source repository}:
109 hosted by GNU savannah.
110
111 @example
112 @uref{http://git.savannah.gnu.org/gitweb/?p=lilypond.git}
113 @end example
114
115 @item @strong{environment variables}:
116 many maintenance scripts, and many instructions in this guide rely on
117 predefined @ref{Environment variables}.
118
119 @item @strong{mailing lists}:
120 given on @rweb{Contact}.
121
122 @item @strong{branches}:
123
124 @itemize
125 @item @code{master}:
126 base your work from this, but do @strong{not push} to it.
127
128 @item @code{staging}:
129 after a successful review (see below), push here.
130
131 @item @code{translation}:
132 translators should base their work from this, and also push to it.
133
134 @item @code{dev/foo}:
135 feel free to push any new branch name under @code{dev/}.
136
137 @end itemize
138
139 @item @strong{regression tests}:
140 also known as @qq{regtests}; this is a collection of more than a
141 thousand .ly files.  We track the output of those files between
142 versions.
143
144 If a patch introduces any unintentional changes to the regtests,
145 we will likely reject it -- make sure that you are aware and can
146 explain any regtest changes.  More info in @ref{Regression tests}.
147
148 @item @strong{reviews}:
149 after finishing work on a patch or branch:
150
151 @enumerate
152 @item
153 upload it with our custom @code{git-cl}.  In addition to uploading
154 it to the google rietveld code review tool, this adds a tracker
155 issue so that we don't lose your patch.  The @qq{status} of your
156 patch is kept on the issue tracker; see @ref{Issues}.
157
158 @example
159 @uref{https://github.com/gperciva/git-cl}
160 @end example
161
162 Your patch will be given @code{Patch-new} status.  More info in
163 @ref{Uploading a patch for review}.
164
165 @item
166 If your patch passes some automatic tests, it will be given
167 @code{Patch-review} status.  This generally happens within 24
168 hours.
169
170 @item
171 After that, the patch must wait for the next @qq{patch countdown},
172 which occur 3 times a week.  If there are a lot of patches waiting
173 for a countdown, a subset of patches are chosen randomly.  When
174 your patch is put on a countdown, it will be given
175 @code{Patch-countdown} status.
176
177 @item
178 The countdown is a 48-hour period which gives other developers one
179 last chance to review the patch.  If no significant problems are
180 found, your patch will be given @code{Patch-push} status.
181
182 @item
183 You may now either push it to the @code{staging} branch, or email
184 your patch (created with @w{@code{git format-patch}}) to somebody
185 who will push it for you.
186
187 @end enumerate
188
189 @advanced{Yes, this process means that most patches wait between
190 60-120 hours before reaching @code{master}.  This is unfortunate, but
191 given our limited resources for reviewing patches and a history of
192 unintended breakage in @code{master}, this is the best compromise
193 we have found.}
194
195 @c I don't think this is important enough to list here, but I may
196 @c change my mind and/or leave a link to a later CG section.
197 @ignore
198 @item @strong{code style}:
199 C++ code should be formatted with
200 @file{scripts/auxiliar/fixcc.py}, which requires
201 @url{http://astyle.sourceforge.net/, astyle 2.02}.  However, we
202 are not very strict about this requirement.
203
204 At the moment, scheme code should be formatted @qq{like emacs does
205 it}.  We are working on an automated tool to simplify this step.
206 However, we are not very strict about this requirement either.
207 @end ignore
208
209 @end itemize
210
211
212 @node Mentors
213 @section Mentors
214
215 We have a semi-formal system of mentorship, similar to the
216 medieval @qq{journeyman/master} training system.  New contributors
217 will have a dedicated mentor to help them @qq{learn the ropes}.
218
219 @warning{This is subject to the availability of mentors; certain
220 jobs have more potential mentors than others.}
221
222 @subheading Contributor responsibilities
223
224 @enumerate
225
226 @item
227 Ask your mentor which sections of the CG you should read.
228
229 @item
230 If you get stuck for longer than 10 minutes, ask your mentor.
231 They might not be able to help you with all problems, but we find
232 that new contributors often get stuck with something that could be
233 solved/explained with 2 or 3 sentences from a mentor.
234
235 @item
236 If you have been working on a task much longer than was originally
237 estimated, stop and ask your mentor.  There may have been a
238 miscommunication, or there may be some time-saving tips that could
239 vastly simply your task.
240
241 @item
242 Send patches to your mentor for initial comments.
243
244 @item
245 Inform your mentor if you're going to be away for a month, or if
246 you leave entirely.  Contributing to lilypond isn't for everybody;
247 just let your mentor know so that we can reassign that work to
248 somebody else.
249
250 @item
251 Inform your mentor if you're willing to do more work -- we always
252 have way more work than we have helpers available.  We try to
253 avoid overwhelming new contributors, so you'll be given less work
254 than we think you can handle.
255
256 @end enumerate
257
258
259 @subheading Mentor responsibilities
260
261 @enumerate
262
263 @item
264 Respond to questions from your contributor(s) promptly, even if
265 the response is just @qq{sorry, I don't know} or @qq{sorry, I'm
266 very busy for the next 3 days; I'll get back to you then}.  Make
267 sure they feel valued.
268
269 @item
270 Inform your contributor(s) about the expected turnaround for your
271 emails -- do you work on lilypond every day, or every weekend, or
272 what?  Also, if you'll be unavailable for longer than usual (say,
273 if you normally reply within 24 hours, but you'll be at a
274 conference for a week), let your contributors know.  Again, make
275 sure they feel valued, and that your silence (if they ask a
276 question during that period) isn't their fault.
277
278 @item
279 Inform your contributor(s) if they need to do anything unusual for
280 the builds, such as doing a @qq{make clean / doc-clean} or
281 switching git branches (not expected, but just in case...)
282
283 @item
284 You don't need to be able to completely approve patches.  Make
285 sure the patch meets whatever you know of the guidelines (for doc
286 style, code indentation, whatever), and then send it on to the
287 frog list or -devel for more comments.  If you feel confident
288 about the patch, you can push it directly (this is mainly intended
289 for docs and translations; code patches should almost always go to
290 -devel before being pushed).
291
292 @item
293 Keep track of patches from your contributor.  Either upload them
294 to Rietveld yourself, or help+encourage them to upload the patches
295 themselves.  When a patch is on Rietveld, it's your responbility
296 to get comments for it, and to add a link to the patch to the
297 google tracker.  (tag it @qq{patch-new}, or @qq{patch-review} if
298 you feel very confident in it)
299
300 @item
301 Encourage your contributor to review patches, particularly your
302 own!  It doesn't matter if they're not familiar with C++ / scheme
303 / build system / doc stuff -- simply going through the process is
304 valuable.  Besides, anybody can find a typo!
305
306 @item
307 Contact your contributor at least once a week.  The goal is just
308 to get a conversation started -- there's nothing wrong with simply
309 copy&pasting this into an email:
310
311 @example
312 Hey there,
313
314 How are things going?  If you sent a patch and got a review, do
315 you know what you need to fix?  If you sent a patch but have no
316 reviews yet, do you know when you will get reviews?  If you are
317 working on a patch, what step(s) are you working on?
318 @end example
319
320
321 @end enumerate
322
323