]> git.donarmstrong.com Git - lilypond.git/blob - Documentation/contributor/administration.itexi
Issue 3420: Stop Documentation/ly-examples/orchestra.ly from redefining markup commands
[lilypond.git] / Documentation / contributor / administration.itexi
1 @c -*- coding: utf-8; mode: texinfo; -*-
2 @node Administrative policies
3 @chapter Administrative policies
4
5 This chapter discusses miscellaneous administrative issues which
6 don't fit anywhere else.
7
8 @menu
9 * Meta-policy for this document::
10 * Environment variables::
11 * Meisters::
12 * Patchy::
13 * Administrative mailing list::
14 * Grand Organization Project (GOP)::
15 * Grand LilyPond Input Syntax Standardization (GLISS)::
16 * Unsorted policies::
17 @end menu
18
19 @node Meta-policy for this document
20 @section Meta-policy for this document
21
22 The Contributor's Guide as a whole is still a work in progress,
23 but some chapters are much more complete than others.  Chapters
24 which are @qq{almost finished} should not have major changes
25 without a discussion on @w{@code{-devel}}; in other chapters, a
26 disorganized @qq{wiki-style dump} of information is encouraged.
27
28 Do not change (other than spelling mistakes) without discussion:
29
30 @itemize
31
32 @item
33 @ref{Introduction to contributing}
34
35 @item
36 @ref{Working with source code}
37
38 @end itemize
39
40 Please dump info in an appropriate @@section within these manuals,
41 but discuss any large-scale reorganization:
42
43 @itemize
44
45 @item
46 @ref{Compiling}
47
48 @item
49 @ref{Documentation work}
50
51 @item
52 @ref{Issues}
53
54 @item
55 @ref{Regression tests}
56
57 @item
58 @ref{Programming work}
59
60
61 @end itemize
62
63 Totally disorganized; do whatever the mao you want:
64
65 @itemize
66
67 @item
68 @ref{Website work}
69
70 @item
71 @ref{LSR work}
72
73 @item
74 @ref{Release work}
75
76 @item
77 @ref{Administrative policies}
78
79 @end itemize
80
81
82 @node Environment variables
83 @section Environment variables
84
85 Some maintenance scripts and instructions in this guide rely on
86 the following environment variables.  They should be predefined in
87 LilyDev distribution (see @ref{LilyDev}); if you set up your own
88 development environment, you can set them by appending these settings to
89 your @file{~/.bashrc} (or whatever defines your default environment
90 variables for the user account for LilyPond development), then logging
91 out and in (adapt directories to your setup):
92
93 @example
94 LILYPOND_GIT=~/lilypond-git
95 export LILYPOND_GIT
96 LILYPOND_BUILD_DIR=~/lilypond-git/build
97 export LILYPOND_BUILD_DIR
98 @end example
99
100 The standard build and install procedure (with @code{autogen.sh},
101 @code{configure}, @code{make}, @code{make install}, @code{make doc}
102 @dots{}) does not rely on them.
103
104 In addition, for working on the website, @code{LILYPOND_WEB_MEDIA_GIT}
105 should be set to the repository lilypond-extra, see
106 @ref{lilypond-extra}.
107
108
109 @node Meisters
110 @section Meisters
111
112 We have four jobs for organizing a team of contributors:
113
114 @itemize
115
116 @item
117 Bug Meister: trains new Bug Squad volunteers, organizes who works
118 on which part of their job, checks to make sure that everything is
119 running smoothly, and has final say on our policy for Issues.
120
121 Currently: Colin H
122
123 @item
124 Doc Meister: trains new doc editors/writers, organizes who works
125 on which part of the job, checks to make sure that everything is
126 running smoothly, and has final say on our policy for
127 Documentation.  Also includes LSR work.
128
129 Currently: Graham
130
131 @item
132 Translation Meister: trains new translators, updates the
133 translation priority list, and handles merging branches (in both
134 directions).
135
136 Currently: Francisco
137
138 @item
139 Frog Meister: is responsible for code patches from (relatively)
140 inexperienced contributors.  Keeps track of patches, does initial
141 reviewing of those patches, sends them to @w{@code{-devel}} when
142 they've had some initial review on the Frog list, pesters the
143 @w{@code{-devel}} community into actually reviewing said patches, and
144 finally pushes the patches once they're accepted.  This person is
145 @emph{not} responsible for training new programmers, because that
146 would be far too much work -- his/her job is @qq{only} to guide
147 completed patches through our process.
148
149 Currently: Mike Solomon
150
151 @end itemize
152
153 @node Patchy
154 @section Patchy
155
156 @subheading Introduction
157
158 Patchy is a set of Python scripts to automate two administrative
159 tasks:
160
161 @itemize
162 @item
163 @code{lilypond-patchy-staging.py}: checks that new commits in
164 @code{staging} can compile the regtests and documentation before
165 merging @code{staging} into @code{master}.
166
167 (completely automatic)
168
169 @item
170 @code{test-patches.py}: checks that patches apply to Git @code{master},
171 compile, and lets a human check that there are no big unintended
172 changes to the regtests.
173
174 (requires some human input)
175
176 @end itemize
177
178 @subheading Installing Patchy
179
180 To install Patchy, you should do the following:
181
182 @enumerate
183 @item
184 Create a new user on your box to run Patchy; this is a security
185 step for your own protection.  It is recommended that this should
186 not be an administrator.  New users are created from System;
187 Administration; Users and Groups.
188
189 @item
190 Get the Patchy scripts from
191 @example
192 @uref{https://github.com/gperciva/lilypond-extra/}
193 @end example
194 Patchy is in the @file{patches/} directory.
195
196 @item
197 Put the scripts and Python libraries contained in @file{patches} in a
198 sensible place on your system; this can be done by appending
199 @file{patches/} full path to the @var{PATH} of the user that runs
200 Patchy.
201
202 @item
203 Create a new git repository with
204 @example
205 git clone git://git.sv.gnu.org/lilypond.git
206 @end example
207 This will create a directory called lilypond with the repo in it.
208 Make sure it's where you want it and name it lilypond-git
209 (assuming you want to follow the standard naming conventions).
210
211 @item
212 Create environment variables @var{LILYPOND_GIT} and
213 @var{LILYPOND_BUILD_DIR}, see @ref{Environment variables}.
214
215 @item
216 Run Patchy once to set up config files, answer @q{@code{n}} when it
217 asks for going on, unless the default config file happens to suit your
218 setup:
219 @example
220 lilypond-patchy-staging.py
221 @end example
222
223 @item
224 Edit @file{$HOME/.lilypond-patchy-config} to provide the location of
225 your local lilypond Git repository, working directories for your build
226 directory, your results directory, compiler options and notification
227 method.  If you don't want to use email notification, then delete
228 everything after @code{smtp_command:}.
229
230 @item
231 Ensure that your new user has git push access.  Follow the
232 instructions in the CG at @ref{Commit access}.  Do not set
233 password protection for the key --- if you do you will not be able
234 to run patchy unattended.
235
236 @end enumerate
237
238 @subheading lilypond-patchy-staging.py
239
240 @code{lilypond-patchy-staging.py} is run with
241 @example
242 python lilypond-patchy-staging.py
243 @end example
244 Not much appears to happen except you can see a lot of CPU gets used
245 if you open System Monitor. There's not much point running
246 @code{lilypond-patchy-staging.py} unless there is something in
247 @code{staging} to be merged to @code{master}, however, if there's
248 nothing new in @code{staging} then the script won't waste resources by
249 compiling anything.
250
251 The script fetches the current patches in staging and runs
252 @code{make}, @code{make test} and @code{make doc} to ensure that all of
253 these complete error-free. If you have set Patchy up to use email,
254 it emails its results to you.  If you haven't, then you can view
255 them in a logfile.  It also merges @code{staging} into @code{master}.
256
257 @warning{in case the build fails, do not try to push fixes on top of
258 staging branch, for details see @ref{Pushing to staging}.}
259
260 When you have run Patchy a few successful times with email sending,
261 you are ready for running it as a cron job. First, make sure you have
262 the following in @file{$HOME/.lilypond-patchy-config} to avoid
263 email flood:
264
265 @example
266 [notification]
267 notify_non_action = no
268 @end example
269
270 Then, assuming Patchy run with user account @code{patchy}, write the
271 following to @file{$HOME/lilypond-patchy.cron}, adapting it as
272 necessary (the @code{/2} means @qq{run this every 2 hours}):
273 @example
274 02 0-23/2 * * * /home/patchy/git/lilypond-extra/patches/lilypond-patchy-staging.py
275 @end example
276
277 @warning{@code{cron} will not inherit environment variables from
278 your main setup, so you must re-define any variables inside
279 @file{$HOME/lilypond-patchy.cron}. For instance, @var{LILYPOND_GIT}
280 may need to be defined if @var{git_repository_dir} is not correctly
281 set in @file{$HOME/.lilypond-patchy-config}.}
282
283 Finally, install the cron job (you may need superuser privileges for
284 this):
285 @example
286 crontab -u patchy /home/patchy/lilypond-patchy.cron
287 @end example
288
289 @subheading test-patches.py
290 @code{test-patches.py} prepares a regtest comparison for a human to
291 quickly glance at, to determine if the patch is ready for a review.
292 After looking at the comparison (or the lack of a comparison in the
293 case of problems), run @code{accept-patch.py} or
294 @code{reject-patch.py}.
295
296 Once a patch has gotten a "LGTM" from Patchy, it should be
297 reviewed by relevant developers, and if it passes this, it can be
298 considered for countdown (see @ref{Commits and patches}) and
299 pushing to staging (see @ref{Pushing to staging}).
300
301
302 @node Administrative mailing list
303 @section Administrative mailing list
304
305 A mailing list for administrative issues is maintained at
306 @code{lilypond-hackers@@gnu.org}.
307
308 This list is intended to be used for discussions that should be kept
309 private. Therefore, the archives are closed to the public.
310
311 Subscription to this list is limited to certain senior developers.
312
313 At the present time, the list is dormant.
314
315 Details about the criteria for membership, the types of discussion
316 to take place on the list, and other policies for the hackers list
317 will be finalized during the
318 @ref{Grand Organization Project (GOP)}.
319
320
321
322 @node Grand Organization Project (GOP)
323 @section Grand Organization Project (GOP)
324
325 GOP has two goals:
326
327 @itemize
328 @item
329 Clarify the various development tasks by writing down the policies
330 and techniques and/or simplifying the tasks directly.
331
332 @item
333 Get more people involved in development: specifically, find people
334 to do easy tasks to allow advanced developers to concentrate on
335 difficult tasks.
336
337 @end itemize
338
339 @menu
340 * Motivation::
341 * Ongoing jobs::
342 * Policy decisions::
343 * Policy decisions (finished)::
344 @end menu
345
346 @node Motivation
347 @subsection Motivation
348
349 Most readers are probably familiar with the LilyPond Grand
350 Documentation Project, which ran from Aug 2007 to Aug 2008. This
351 project involved over 20 people and resulted in an almost complete
352 rewrite of the documentation. Most of those contributors were
353 normal users who decided to volunteer their time and effort to
354 improve lilypond for everybody. By any measure, it was a great
355 success.
356
357 The Grand Organization Project aims to do the same thing with a
358 larger scope -- instead of focusing purely on documentation, the
359 project aims to improve all parts of LilyPond and its community.
360 Just as with GDP, the main goal is to encourage and train users to
361 become more involved.
362
363 If you have never contributed to an open-source project before --
364 especially if you use Windows or OSX and do not know how to
365 program or compile programs -- you may be wondering if there's
366 anything you can do. Rest assured that you @emph{can} help.
367
368 @subheading "Trickle-up" development
369
370 One of the reasons I'm organizing GOP is "trickle-up"
371 development.  The idea is this: doing easy tasks frees up advanced
372 developers to do harder tasks.  Don't ask "am I the @emph{best}
373 person for this job"; instead, ask "am I @emph{capable} of doing
374 this job, so that the current person can do stuff I @emph{can't}
375 do?".
376
377 For example, consider lilypond's poor handling of grace notes in
378 conjunction with clef and tempo changes. Fixing this will require
379 a fair amount of code rewriting, and would take an advanced
380 developer a few weeks to do. It's clearly beyond the scope of a
381 normal user, so we might as well sit back and do nothing, right?
382
383 No; we @emph{can} help, indirectly. Suppose that our normal user
384 starts answering more emails on lilypond-user. This in turn means
385 that documentation writers don't need to answer those emails, so
386 they can spend more time improving the docs. I've noticed that all
387 doc writers tackle harder and harder subjects, and when they start
388 writing docs on scheme programming and advanced tweaks, they start
389 contributing bug fixes to lilypond. Having people performing these
390 easy-to-moderate bug fixes frees up the advanced developers to
391 work on the really hard stuff... like rewriting the grace note
392 code.
393
394 Having 1 more normal user answering emails on lilypond-user won't
395 have a dramatic @q{trickle-up} effect all by itself, of course. But if
396 we had 8 users volunteering to answer emails, 6 users starting to
397 write documentation, and 2 users editing LSR... well, that would
398 free up a lot of current bug-fixing-capable contributors to focus
399 on that, and we could start to make a real dent in the number of
400 bugs in lilypond. Quite apart from the eased workload, having that
401 many new helpers will provide a great moral boost!
402
403 @node Ongoing jobs
404 @subsection Ongoing jobs
405
406 Although GOP is a short-term project, the main goal is to train
407 more people to handle ongoing jobs. The more people doing these
408 jobs, the lighter the work will be, and the more we can get done
409 with lilypond!
410
411 Also, it would be nice if we had at least one "replacement" /
412 "understudy" for each role -- too many tasks are only being done
413 by one person, so if that person goes on vacation or gets very
414 busy with other matters, work in that area grinds to a halt.
415
416 @subheading Jobs for normal users
417
418 @itemize
419 @item Consultant:
420 LilyPond is sometimes critized for not listening to users, but
421 whenever we ask for opinions about specific issues, we never get
422 enough feedback. This is somewhat aggravating.
423 We need a group of users to make a dedicated effort to test and
424 give feedback. If there's new documentation, read it. If there's
425 an experimental binary, download it and try compiling a score with
426 it. If we're trying to name a new command, think about it and give
427 serious suggestions.
428
429 @item lilypond-user support:
430 I think it would be nice if we had an official team of users
431 helping other users.
432
433 @item LilyPond Report:
434 Keeping a monthly newsletter running is a non-trivial task.  A lot
435 of work is needed to organize it; it would be great if we could
436 split up the work. One person could write the Snippet of the
437 Month, another person could do Quotes of the Month, another person
438 could do interviews, etc.
439
440 @item Documentation:
441 Although GDP (the Grand Documentation Project) did great work,
442 there's still many tasks remaining.
443
444 @item Translations:
445 Keeping the documentation translations is a monumental task; we
446 need all the help we can get!
447
448 @end itemize
449
450 @subheading Jobs for advanced users for developers
451
452 @itemize
453 @item Git help for writers:
454 We often receive reports of typos and minor text updates to the
455 documentation. It would be great if somebody could create
456 properly-formatted patches for these corrections.
457
458 Technical requirements: ability to run @ref{LilyDev}.
459
460 @item LSR editor:
461 LSR contains many useful examples of lilypond, but some snippets
462 are out of date and need updating. Other snippets need to be
463 advertized, and new snippets need to be sorted. We could use
464 another person to handle LSR.
465
466 Technical requirements: use of a web browser. LilyPond
467 requirements: you should be familiar with most of Notation
468 chapters 1 and 2 (or be willing to read the docs to find out).
469
470 @item Join the Frogs:
471 "Frogs" are a team of bug-fixers (because frogs eat bugs, and you
472 often find them in Ponds of Lilies) and new feature implementors.
473
474 Technical requirements: development environment (such as
475 @ref{LilyDev}), ability to read+write scheme and/or C++ code.
476
477 @end itemize
478
479
480 @node Policy decisions
481 @subsection Policy decisions
482
483 There are a number of policy decisions -- some of them fairly
484 important -- which we have been postponing for a few years.  We
485 are now discussing them slowly and thoroughly; agenda and exact
486 proposals are online:
487
488 @example
489 @uref{http://lilypond.org/~graham/gop/index.html}
490 @end example
491
492 Below is a list of policies which are not @qq{on the agenda} yet.
493
494 Note that the presence of an item on this list does @emph{not}
495 mean that everybody thinks that something needs to be done.
496 Inclusion in this simply means that one developer thinks that we
497 should discuss it.  We are not going to filter this list; if any
498 developer thinks we should discuss something, just add it to the
499 bottom of the list.  (the list is unsorted)
500
501 As GOP progresses, items from this list will be put on the agenda
502 and removed from this list.  I generally try to have one month's
503 discussion planned in advance, but I may shuffle things around to
504 respond to any immediate problems in the developer community.
505
506 There are some item(s) not displayed here; these are questions
507 that were posed to me privately, and I do not feel justified in
508 discussing them publicly without the consent of the person(s) that
509 brought them up. They will initially be discussed privately on the
510 lilypond-hackers mailing list -- but the first question will be
511 "do we absolutely need to do this privately", and if not, the
512 discussion will take place on lilypond-devel like the other items.
513
514 In most policy discussions in lilypond over the past few years,
515 the first half (or more) is wasted arguing on the basis of
516 incorrect or incomplete data; once all the relevant facts are
517 brought to light, the argument is generally resolved fairly
518 quickly.  In order to keep the GOP discussions focused, each topic
519 will be introduced with a collection of relevant facts and/or
520 proposals.  It is, of course, impossible to predict exactly which
521 facts will be relevant to the discussion -- but spending an hour
522 or two collecting information could still save hours of
523 discussion.
524
525 @warning{The estimated time required for "prep work", and the
526 following discussion, has been added to each item.  At the moment,
527 there is an estimated 30 hours of prep work and 140 hours of
528 discussion.}
529
530 @itemize
531 @item @strong{Patch reviewing}:
532 At the time of this writing, we have 23 (known) patches waiting
533 for review.  Some from main developers; some from new developers.
534 We desperately need more people helping with lilypond, but
535 ignoring patches is the best way to drive potential contributors
536 away.  This is not good.
537
538 (prep: 2 hours.  discuss: 10 hours)
539
540 @item @strong{Official links to other organizations?}:
541 There's something called the "software freedom conservancy", and
542 in general, there's a bunch of "umbrella organizations". Joining
543 some of these might give us more visibility, possibly leading to
544 more users, more developers, maybe even financial grants or use in
545 schools, etc.
546
547 (prep: 2 hours.  discuss: 5 hours)
548
549 @item @strong{Issue tracking with google code}:
550 We use the google issue tracker, but this means that we are
551 relying on a commercial entity for a large part of our
552 development. Would it be better (safer in the long run) to use the
553 savannah bug tracker?
554
555 (prep: 1 hour.  discuss: 5 hours)
556
557 @item @strong{Patch review tool}:
558 Reitveld is inconvenient in some respects: it requires a google
559 account, and there's no way to see all patches relating to
560 lilypond. Should we switch to something like gerritt?
561 @uref{http://code.google.com/p/lilypond/issues/detail?id=1184}
562
563 (prep: 5 hours.  discuss: 15 hours)
564
565 @item @strong{Clarity for sponsorships}:
566 We currently do not advertize bounties and sponsorships on the
567 webpage.  How much advertising do we want, and what type?
568 Should we change the "structure" / "framework" for bounties?
569
570 (prep: 2 hours.  discuss: 10 hours)
571
572 @item @strong{code readability}:
573 "Our aim when producing source code for Lilypond in whatever
574 language is that it should be totally comprehensible to a
575 relatively inexperienced developer at the second reading."
576
577 Rationale:
578 - aids maintainability of code base
579 - "second reading" so newer developers can look up unfamiliar
580   stuff
581 - will help to keep things simple, even if the code is doing
582   complex stuff discourages "secret squirrel" coding, e.g.  "how
583   much functionality can I squeeze into as few characters as
584   possible" "comments are for wimps"
585 - will aid not *discouraging* new developers to join the project
586
587 (prep: 2 hours.  discuss: 10 hours)
588
589 @item @strong{C++ vs. scheme}:
590 what should be in scheme, what should be in C++, what can/should
591 be ported from one to the other, etc.  Questions of
592 maintainability, speed (especially considering guile 2.0), and the
593 amount of current material in either form, are important.
594
595 (prep: 5 hours.  discuss: 15 hours)
596
597 @item @strong{always make an issue number for patches}:
598 there is a proposal that we should always have a google code issue
599 number for every patch.  This proposal is closely tied to our
600 choice of patch review tool; if we switch to a different tool (as
601 suggested in a different proposal), this proposal may become moot.
602
603 (prep: 1 hour.  discuss: 5 hours)
604
605 @item @strong{initalizer lists}:
606 shoudl we use initalizer lists for C++?  AFAIK they make no
607 difference for built-in types, but there's some weird case where
608 it's more efficient for objects, or something.
609
610 Probably not worth making this a weekly thing on its own, but we
611 can probably wrap it up with some other code-related questions.
612
613 (prep: 15 minutes.  discuss: 3 hours)
614
615 @end itemize
616
617 @node Policy decisions (finished)
618 @subsection Policy decisions (finished)
619
620 Here is a record the final decisions, along with links to the
621 discussions.
622
623 @menu
624 * GOP-PROP 1 - python formatting::
625 * GOP-PROP 2 - mentors and frogs::
626 * GOP-PROP 3 - C++ formatting::
627 * GOP-PROP 4 - lessons from 2.14::
628 * GOP-PROP 5 - build system output (not accepted)::
629 * GOP-PROP 6 - private mailing lists::
630 * GOP-PROP 7 - developers as resources::
631 * GOP-PROP 8 - issue priorities::
632 * GOP-PROP 9 - behavior of make doc::
633 @end menu
634
635 @node GOP-PROP 1 - python formatting
636 @subsubsection GOP-PROP 1 - python formatting
637
638 We will follow the indentation described in PEP-8.
639 @uref{http://www.python.org/dev/peps/pep-0008/}
640
641 @itemize
642 @item
643 use 4 spaces per indentation level
644
645 @item
646 never mix tabs and spaces (for indentation)
647
648 @item
649 Code indented with a mixture of tabs and spaces should be
650 converted to using spaces exclusively
651
652 Once this is done, we should add @code{python -tt} to the build
653 system to avoid such errors in the future.
654
655 @end itemize
656
657 There should be absolutely no tab characters for indentation in
658 any @code{.py} file in lilypond git.  All such files should be
659 converted to use spaces only.
660
661 @subsubheading Discussions
662
663 @smallexample
664 @uref{https://lists.gnu.org/archive/html/lilypond-devel/2011-06/msg00060.html}
665 @uref{https://lists.gnu.org/archive/html/lilypond-devel/2011-06/msg00084.html}
666 @uref{https://lists.gnu.org/archive/html/lilypond-devel/2011-06/msg00310.html}
667 @uref{https://lists.gnu.org/archive/html/lilypond-devel/2011-06/msg00574.html}
668 @end smallexample
669
670
671 @node GOP-PROP 2 - mentors and frogs
672 @subsubsection GOP-PROP 2 - mentors and frogs
673
674 Nothing much was decided.  The list of responsibilities was
675 slightly altered; see the new one in @ref{Mentors}.  We should
676 encourage more use of the Frogs mailing list.  There's a list of
677 contributor-mentor pairs in:
678
679 @smallexample
680 @uref{https://github.com/gperciva/lilypond-extra/blob/master/people/mentors.txt}
681 @end smallexample
682
683 That's pretty much it.
684
685 @subsubheading Discussions
686
687 @smallexample
688 @uref{https://lists.gnu.org/archive/html/lilypond-devel/2011-06/msg00311.html}
689 @uref{}
690 @uref{}
691 @end smallexample
692
693
694 @node GOP-PROP 3 - C++ formatting
695 @subsubsection GOP-PROP 3 - C++ formatting
696
697 Speaking academically, C++ code style is a "solved problem". Let's
698 pick one of the existing solutions, and let a computer deal with
699 this.  Humans should not waste their time, energy, and creativity
700 manually adding tabs or spaces to source code.
701
702 We have modified @code{fixcc.py} to use astyle, along with extra
703 regex tweaks.
704
705 @itemize
706 @item
707 the final script will be run @strong{blindly} on the lilypond
708 source code.  We will accept whatever formatting the final version
709 of this script produces, with no manual tweaking.
710
711 @item
712 patches which have been run through this tool will not be rejected
713 for style reasons.  Any code formatting @qq{desires} which are not
714 enforced by @code{fixcc.py} will not be considered grounds for
715 rejecting a patch.
716
717 @item
718 for now, this style will not be enforced.  It is not cause for
719 concern if patches which do not follow the formatting done by
720 @code{fixcc.py} are pushed.  From time to time, Graham will run
721 the formatter on the entire code base, and commit the resulting
722 changes.
723
724 In a few months, we will tighten up this policy item (with some
725 sort of automatic processing), but that is outside the scope of
726 this policy item and is a matter for later discussion.
727
728 @item
729 after the proposal is accepted, we will leave some time for
730 existing patches to be accepted and pushed.  The script was
731 run on the source code on @strong{2011 August 01}.
732
733 @end itemize
734
735 @subheading GNU code
736
737 LilyPond is a GNU project, so it makes sense to follow the GNU
738 coding standards.  These standards state:
739
740 @quotation
741 We don’t think of these recommendations as requirements, because
742 it causes no problems for users if two different programs have
743 different formatting styles.
744
745 But whatever style you use, please use it consistently, since a
746 mixture of styles within one program tends to look ugly. If you
747 are contributing changes to an existing program, please follow the
748 style of that program. 
749 @end quotation
750
751 (@uref{http://www.gnu.org/prep/standards/html_node/Formatting.html})
752
753 With that in mind, we do not think that we must blindly follow the
754 formatting given by the currrent version of Emacs.
755
756 @subheading Implementation notes
757
758 We can avoid some of the style change pollution in git history by
759 ignoring whitespaces changes:
760
761 @example
762 git diff -w
763 @end example
764
765 @subsubheading Discussions
766
767 @smallexample
768 @uref{https://lists.gnu.org/archive/html/lilypond-devel/2011-06/msg00526.html}
769 @uref{https://lists.gnu.org/archive/html/lilypond-devel/2011-06/msg00796.html}
770 @uref{https://lists.gnu.org/archive/html/lilypond-devel/2011-07/msg00200.html}
771 @uref{https://lists.gnu.org/archive/html/lilypond-devel/2011-07/msg00525.html}
772 @uref{https://lists.gnu.org/archive/html/lilypond-devel/2011-07/msg00751.html}
773 @uref{https://lists.gnu.org/archive/html/lilypond-devel/2011-07/msg00751.html}
774 @end smallexample
775
776
777 @node GOP-PROP 4 - lessons from 2.14
778 @subsubsection GOP-PROP 4 - lessons from 2.14
779
780 @subheading History
781
782 A brief history of releases:
783
784 @multitable @columnfractions .2 .2 .3
785 @headitem date (YYYY-MM-DD) @tab version @tab comment
786 @item 2008-10-28 @tab 2.11.63 @tab nobody checking regtests
787 @item 2008-11-17 @tab 2.11.64
788 @item 2008-11-29 @tab 2.11.65
789 @item 2008-12-23 @tab 2.12.0
790 @item 2009-01-01 @tab @tab somewhere around here, Graham becomes
791 officially release manager, but Han-Wen still builds the actual
792 releases
793 @item 2009-01-01 @tab 2.12.1
794 @item 2009-01-25 @tab 2.12.2
795 @item 2009-02-28 @tab 2.13.0
796 @item 2009-06-01 @tab 2.13.1 @tab note jump in time!
797 @item 2009-06-27 @tab 2.13.2 @tab first Graham release?
798 @item 2009-07-03 @tab 2.13.3
799 @item 2009-09-09 @tab @tab Graham arrives in Glasgow, gets a
800 powerful desktop computer, and begins serious work on GUB (sending
801 bug reports to Jan).  It takes approximately 100 hours until GUB
802 is stable enough to make regular releases.
803 @item 2009-09-24 @tab 2.13.4
804 @item 2009-10-02 @tab 2.13.5
805 @item 2009-10-22 @tab 2.13.6
806 @item 2009-11-05 @tab 2.13.7
807 @item ...
808 @item 2010-01-13 @tab 2.12.3
809 @item ...
810 @item 2010-03-19 @tab 2.13.16 @tab Bug squad starts doing a few
811 regtest comparisons, but IIRC the effort dies out after a few
812 weeks (BLUE)
813 @item ...
814 @item 2010-08-04 @tab 2.13.29 @tab Phil starts checking regtests (BLUE)
815 @item ...
816 @item 2011-01-12 @tab 2.13.46 @tab release candidate 1 (GREEN)
817 @item ...
818 @item 2011-05-30 @tab 2.13.63 @tab release candidate 7 (GREEN)
819 @item 2011-06-06 @tab 2.14.0
820 @end multitable
821
822 @c A graphical display of bugs:
823 @c 
824 @c @image{bugs-2.13-visualization,png}
825 @c @image{zoom-2.13-visualization,png}
826
827 @subheading Carl's analysis of the bugs
828
829 A @file{csv} spreadsheet is available.
830
831 @smallexample
832 @uref{https://lists.gnu.org/archive/html/lilypond-devel/2011-06/msg00852.html}
833 @end smallexample
834
835 @example
836 @uref{lilypond-issues-analysis.csv}
837 @uref{lilypond-issues-analysis-trim-duplicates.csv}
838 @end example
839
840 There 148 issues marked with Priority=Critical in the tracker.
841
842 I've done an analysis, and it looks to me like there was initially
843 a backlog of critical issues that weren't fixed, and little work
844 was being done to eliminate critical issues.
845
846 Somewhere about 2010-08-01, critical issues started to disappear,
847 but occasional new ones appeared.
848
849 There were a couple of major changes that introduced unanticipated
850 regressions (new spacing code, beam collision avoidance).  These
851 produced more than the expected number of regressions.
852
853 It appears to me that we didn't really get serious about
854 eliminating critical bugs until about 2010-06-15 or so.  After
855 that point, the number of critical bugs more-or-less steadily
856 decreased until we got to a release candidate.
857
858 Of particular interest, the first release candidate of 2.14 was
859 released on 2011-01-12.  Over the next 10 days, about a dozen bugs
860 were reported and fixed.  Release candidate 2 came out on
861 2011-02-09.   No surge of bugs occurred with this release.
862 Candidate 3 came out on 2011-03-13; we got 2 bugs per week.
863 Candidate 4 came out on 2011-03-29; 2 new bugs.  Candidate 6 came
864 out on 2011-04-07.  We got a couple of bugs per week.
865
866 @subheading Notes, commentary, and opinions
867
868 @example
869 Han-Wen: Overall, I think this cycle took too long
870 Mike: I agree
871 Graham: +1
872 @end example
873
874 @subsubheading Discussions
875
876 @smallexample
877 @uref{https://lists.gnu.org/archive/html/lilypond-devel/2011-06/msg00797.html}
878 @uref{https://lists.gnu.org/archive/html/lilypond-devel/2011-07/msg00364.html}
879 @uref{}
880 @end smallexample
881
882
883 @node GOP-PROP 5 - build system output (not accepted)
884 @subsubsection GOP-PROP 5 - build system output (not accepted)
885
886 This proposal was too broad; after a month of discussion, Graham
887 withdrew the proposal.  Portions of it will be introduced in later
888 proposals.
889
890 @subsubheading Discussions
891
892 @smallexample
893 @uref{https://lists.gnu.org/archive/html/lilypond-devel/2011-07/msg00320.html}
894 @uref{https://lists.gnu.org/archive/html/lilypond-devel/2011-07/msg00527.html}
895 @uref{https://lists.gnu.org/archive/html/lilypond-devel/2011-07/msg00753.html}
896 @uref{https://lists.gnu.org/archive/html/lilypond-devel/2011-07/msg01042.html}
897 @uref{https://lists.gnu.org/archive/html/lilypond-devel/2011-08/msg00116.html}
898 @uref{https://lists.gnu.org/archive/html/lilypond-devel/2011-08/msg00310.html}
899 @end smallexample
900
901
902 @node GOP-PROP 6 - private mailing lists
903 @subsubsection GOP-PROP 6 - private mailing list
904
905 Potentially sensitive or private matters will be referred to
906 Graham.  He will then decide who should discuss the matter on an
907 ad-hoc basis, and forward or CC them on future emails.
908
909 For emphasis, the project administrators are Han-Wen, Jan, and
910 Graham; those three will always be CC'd on any important
911 discussions.
912
913 The lilypond-hackers mailing list will be removed.
914
915 @subheading History
916
917 There is some unhappy history about this idea in our development
918 community:
919
920 @example
921 @uref{http://lists.gnu.org/archive/html/lilypond-devel/2010-09/msg00178.html}
922 @uref{http://news.lilynet.net/spip.php?article121}
923 @uref{http://lists.gnu.org/archive/html/lilypond-devel/2010-11/msg00076.html}
924 @end example
925
926 @subheading Other projects
927
928 The idea of private mailing lists is hardly uncommon in
929 open-source software.  For example,
930
931 @example
932 @uref{http://lwn.net/Articles/394660/}   about debian-private
933 @uref{http://subversion.apache.org/mailing-lists.html}  private@@
934 @uref{http://www.freebsd.org/administration.html#t-core}
935 @uref{http://foundation.gnome.org/legal/}   board members pledge
936 to keep certain matters confidential
937
938 every security team of every GNU/Linux distribution and OS
939 @end example
940
941 In fact, Karl Fogel's @qq{Producing Open Source Software}
942 explicitly suggests a private mailing list for some circumstances:
943
944 @example
945 [on granting commit/push access to a contributor]
946
947 But here is one of the rare instances where secrecy is
948 appropriate. You can't have votes about potential committers
949 posted to a public mailing list, because the candidate's feelings
950 (and reputation) could be hurt.
951
952 @uref{http://producingoss.com/en/consensus-democracy.html#electorate}
953 @end example
954
955 @subheading Board of governers, voting, etc?
956
957 Many projects have an official board of directors, or a list of
958 @qq{core developers}, with set term limits and elections and
959 stuff.
960
961 I don't think that we're that big.  I think we're still small
962 enough, and there's enough trust and consensus decisions, that we
963 can avoid that.  I would rather that we kept on going with
964 trust+consensus for at least the next 2-3 years, and spent more
965 time+energy on bug fixes and new features instead of
966 administrative stuff.
967
968 Project administrators are Han-Wen, Jan, and Graham.
969
970 @subsubheading Discussions
971
972 @smallexample
973 @uref{https://lists.gnu.org/archive/html/lilypond-devel/2011-07/msg00783.html}
974 @uref{https://lists.gnu.org/archive/html/lilypond-devel/2011-07/msg01004.html}
975 @uref{https://lists.gnu.org/archive/html/lilypond-devel/2011-08/msg00117.html}
976 @end smallexample
977
978
979 @node GOP-PROP 7 - developers as resources
980 @subsubsection GOP-PROP 7 - developers as resources
981
982 We shall treat developers (and contributors) as
983 @strong{Independent volunteers}: each person does whatever they
984 want, whenever they want.  We have busy careers and lives; we make
985 no expectations of action from anybody (with the exception of the
986 6 people in @qq{Meister} positions).
987
988 @subsubheading Discussions
989
990 @smallexample
991 @uref{https://lists.gnu.org/archive/html/lilypond-devel/2011-07/msg01092.html}
992 @uref{https://lists.gnu.org/archive/html/lilypond-devel/2011-08/msg00087.html}
993 @uref{https://lists.gnu.org/archive/html/lilypond-devel/2011-08/msg00497.html}
994 @end smallexample
995
996
997 @node GOP-PROP 8 - issue priorities
998 @subsubsection GOP-PROP 8 - issue priorities
999
1000 We will delete the @qq{priority} field of the issue tracker
1001 altogether.  The @qq{type} system will be tweaked.
1002
1003 Type-critical:
1004
1005 @itemize
1006
1007 @item
1008 a reproducible failure to build either @code{make} or @code{make
1009 doc}, from an empty build tree, in a first run, if
1010 @code{configure} does not report any errors.
1011
1012 @item
1013 any program behaviour which is @strong{unintentionally} worse than
1014 the previous stable version or the current development version.
1015 Developers may always use the @qq{this is intentional}, or even
1016 the @qq{this is an unavoidable effect of an improvement in another
1017 area}, reason to move this to a different type.
1018
1019 @item
1020 anything which stops contributors from helping out (e.g.
1021 lily-git.tcl not working, source tree(s) not being available,
1022 LilyDev being unable to compile git master, inaccurate
1023 instructions in the Contributor's Guide 2 Quick start).
1024
1025 To limit this scope of this point, we will assume that the
1026 contributor is using the latest LilyDev and has read the relevant
1027 part(s) of the Contributor's Guide.  Problems in other chapters of
1028 the CG are not sufficient to qualify as Type-Critical.
1029
1030 @end itemize
1031
1032 @subsubheading More new/changed types and labels
1033
1034 Unless otherwise specified, the current types and labels will
1035 continue to be used.  The new types introduced by this proposal
1036 are:
1037
1038 @itemize
1039
1040 @item
1041 Type-crash: any segfault, regardless of what the input file looks
1042 like or which options are given.  Disclaimer: this might not be
1043 possible in some cases, for example certain guile programs (we
1044 certainly can't predict if a piece of scheme will ever stop
1045 running, i.e. the halting problem), or if we rely on other
1046 programs (i.e. ghostscript).  If there are any such cases that
1047 make segfault-prevention impossible, we will document those
1048 exceptions (and the issue will remain as a "crash" instead of
1049 "documentation" until the warning has been pushed).
1050
1051 @item
1052 Type-maintainability: anything which makes it difficult for
1053 serious contributors to help out (e.g. difficult to find the
1054 relevant source tree(s), confusing policies, problems with
1055 automatic indentation tools, etc).
1056
1057 @item
1058 Type-ugly: replaces Type-collision, and it will include things
1059 like bad slurs in addition to actual collision.
1060
1061 @end itemize
1062
1063 A new label will be added:
1064
1065 @itemize
1066 @item
1067 (label) Needs_evidence: it is not clear what the correct output
1068 should look like.  We need scans, references, examples, etc.
1069
1070 @end itemize
1071
1072 @subheading Reminding users about stars
1073
1074 We can remind users that they can @qq{star} an issue to indicate
1075 that they care about it.  Since we resolved to treat developers as
1076 independent volunteers, there is no expectation that anybody will
1077 look at those stars, but if any developer want to organize their
1078 work schedule according to the stars, they are welcome to do so.
1079
1080 @subsubheading Discussions
1081
1082 @smallexample
1083 @uref{https://lists.gnu.org/archive/html/lilypond-devel/2011-08/msg00019.html}
1084 @uref{https://lists.gnu.org/archive/html/lilypond-devel/2011-08/msg00277.html}
1085 @uref{https://lists.gnu.org/archive/html/lilypond-devel/2011-08/msg00413.html}
1086 @uref{https://lists.gnu.org/archive/html/lilypond-devel/2011-08/msg00624.html}
1087 @uref{}
1088 @end smallexample
1089
1090
1091 @node GOP-PROP 9 - behavior of make doc
1092 @subsubsection GOP-PROP 9 - behavior of make doc
1093
1094 If there are build problems, then it should be easier to find out
1095 why it's failing.  This will be achieved with log files, as well
1096 as possibly including scripts which automatically display portions
1097 of those log files for a failing build.
1098
1099 We will also add targets for building a specific manual (for
1100 quick+easy checking of doc work), as well as for building all
1101 documentation in a specific language (either English or a
1102 translated language).
1103
1104 When you run @code{make doc},
1105
1106 @itemize
1107
1108 @item
1109 All output will be saved to various log files, with the exception
1110 of output directly from @code{make(1)}.
1111
1112 Note that @code{make(1)} refers to a specific executable file on
1113 unix computers, and is not a general term for the build system.
1114
1115 @item
1116 By default, no other output will be displayed on the console, with
1117 one exception: if a build fails, we might display some portion(s)
1118 of log file(s) which give useful clues about the reason for the
1119 failure.
1120
1121 The user may optionally request additional output to be printed;
1122 this is controlled with the @code{VERBOSE=x} flag.  In such cases,
1123 all output will still be written to log files; the console output
1124 is strictly additional to the log files.
1125
1126 @item
1127 Logfiles from calling lilypond (as part of lilypond-book) will go in
1128 the relevant
1129 @file{$LILYPOND_BUILD_DIR/out/lybook-db/12/lily-123456.log} file.  All
1130 other logfiles will go in the @file{$LILYPOND_BUILD_DIR/logfiles/}
1131 directory.
1132
1133 A single @code{make doc} will therefore result in hundreds of log
1134 files.  Log files produced from individual lilypond runs are not
1135 under our control; apart from that, I anticipate having one or two
1136 dozen log files.  As long as it is clear which log file is
1137 associated with which operation(s), I think this is entirely
1138 appropriate.  The precise implementation will be discussed for
1139 specific patches as they appear.
1140
1141 @item
1142 Both stderr and stdout will be saved in @code{*.log}.  The order
1143 of lines from these streams should be preserved.
1144
1145 @item
1146 There will be no additional @qq{progress messages} during the
1147 build process.  If you run @code{make --silent}, a non-failing
1148 build should print absolutely nothing to the screen.
1149
1150 @item
1151 Assuming that the loglevels patch is accepted, lilypond (inside
1152 lilypond-book) will be run with --loglevel=WARN.
1153 @uref{http://codereview.appspot.com/4822055/}
1154
1155 @item
1156 Ideally, a failing build should provide hints about the reason why
1157 it failed, or at least hints about which log file(s) to examine.
1158
1159 @end itemize
1160
1161 If this proposal is accepted, none of these policies will be
1162 assumed to apply to any other aspect of the build system.
1163 Policies for any other aspect of the build system will be
1164 discussed in separate proposals.
1165
1166 @subheading Don't cause more build problems
1167
1168 However, there is a danger in this approach, that vital error
1169 messages can also be lost, thus preventing the cause of the
1170 failure of a make being found.  We therefore need to be
1171 exceptionally careful to move cautiously, include plenty of tests,
1172 and give time for people to experiment/find problems in each stage
1173 before proceeding to the next stage.
1174
1175 This will be done by starting from individual lilypond calls
1176 within lilypond-book, and slowly moving to @qq{larger} targets of
1177 the build system -- after the individual lilypond calls are are
1178 producing the appropriate amount of output and this is saved in
1179 the right place and we can automatically isolate parts of a
1180 failing build, we will work on lilypond-book in general, and only
1181 then will we look at the build system itself.
1182
1183 @subheading Implementation notes
1184
1185 There is an existing make variable QUIET_BUILD, which
1186 alter the amount of output being displayed
1187 (@uref{
1188 http://lilypond.org/doc/v2.15/Documentation/contributor/useful-make-variables}
1189 ).  We are not planning on keeping this make variable.
1190
1191 The standard way for GNU packages to give more output is with a
1192 @code{V=x} option.  Presumably this is done by increasing
1193 @code{x}?  If we support this option, we should still write log
1194 files; we would simply print more of the info in those log files
1195 to screen.
1196
1197 The command @code{tee} may be useful to write to a file and
1198 display to stdout (in the case of VERBOSE).
1199
1200
1201 @subsubheading Discussions
1202
1203 @smallexample
1204 @uref{https://lists.gnu.org/archive/html/lilypond-devel/2011-08/msg00378.html}
1205 @uref{https://lists.gnu.org/archive/html/lilypond-devel/2011-08/msg00703.html}
1206 @end smallexample
1207
1208
1209 @ignore
1210 @n ode GOP-PROP 10 - scheme indentation
1211 @s ubsubsection GOP-PROP 10 - scheme indentation
1212
1213 still under discussion
1214
1215 @subsubheading Discussions
1216
1217 @smallexample
1218 @uref{https://lists.gnu.org/archive/html/lilypond-devel/2011-08/msg00625.html}
1219 @uref{https://lists.gnu.org/archive/html/lilypond-devel/2011-08/msg01026.html}
1220 @c @uref{}
1221 @end smallexample
1222 @end ignore
1223
1224
1225
1226 @node Grand LilyPond Input Syntax Standardization (GLISS)
1227 @section Grand LilyPond Input Syntax Standardization (GLISS)
1228
1229 @subheading Summary
1230
1231 @itemize
1232 @item
1233 Start: sortly after 2.14 comes out, which is currently estimated
1234 to happen in January 2011.
1235
1236 @item
1237 Length: 6-12 months.  We're not going to rush this.
1238
1239 @item
1240 Goal: define an input which we commit to being
1241 machine-updateable for the forseeable future.  Any future patches
1242 which change the syntax in a non-convert-ly-able format will be
1243 rejected.  (subject to the limitations, below)
1244 Once this is finished, we will release lilypond 3.0.
1245
1246 @end itemize
1247
1248
1249 @subheading The Problem
1250
1251 One of the biggest complaints people have with lilypond -- other
1252 than silly thing like "there's no gui" -- is the changing syntax.
1253 Now, inventing a language or standards is difficult.  If you set
1254 it in stone too soon, you risk being stuck with decisions which
1255 may limit matters.  If you keep on updating the syntax,
1256 interaction with older data (and other programs!) becomes complex.
1257
1258 @subheading Scope and Limitations
1259
1260 @itemize
1261 @item
1262 tweaks will not be included.  Anything with \override, \set,
1263 \overrideProperty, \tweak, \revert, \unset... including even those
1264 command names themselves... is still fair game for NOT_SMART
1265 convert-ly updates.
1266
1267 @item
1268 other than that, everything is on the table.  Is it a problem to
1269 have the tagline inside \header?  What should the default behavior
1270 of \include be?
1271
1272 @item
1273 we need to get standards for command names.  This will help users
1274 remember them, and reduce the options for future names (and
1275 potential renamings later on).  \commandOn and \commandOff seem to
1276 work well (should we *always* have an Off command?), but what
1277 about the "command" part?  Should it be \nounVerbOn, or
1278 \verbNounOn ?  Or \verbNotesWithExtraInformationOn ?
1279
1280 @item
1281 we need standards for the location of commands.  Ligature
1282 brackets, I'm looking at you.  (non-postfix notation must die!)
1283
1284 @item
1285 this Grand Project doesn't affect whether we have a 2.16 or not.
1286 The main problem will be deciding what to do (with a bit of
1287 messiness anticipated for \tuplet); we should definitely release a
1288 2.16 before merging _any_ of these changes.
1289
1290 @item
1291 we obviously can't /guarantee/ that we'll /never/ make any
1292 non-convert-ly changes in the basic format.  But we *can*
1293 guarantee that such changes would force lilypond 4.0, and that we
1294 would only do so for overwhelmingly good reasons.
1295
1296 @end itemize
1297
1298 @subheading Workflow
1299
1300 @itemize
1301 @item
1302 We're going to have lots and lots of emails flying around.  The
1303 vast majority won't really fit into either -devel or -user, so
1304 we'll use a list devoted to syntax issues.
1305
1306 @item
1307 Once we have a serious proposal that gained general acceptance
1308 from the separate syntax mailing list, I'll bring it to -devel.
1309 We're not going to make any changes without discussing it on
1310 -devel, but if we're going to have huge threads about English
1311 grammar and silly ideas, and I don't want to clutter up -devel.
1312 Once whatever chaotic silliness on the syntax list is settled
1313 down, I'll bring the ideas to -devel.
1314
1315 @item
1316 as with GDP, I'll moderate the discussion.  Not as with mailist
1317 moderation, but rather by introducing issues at specific times.
1318 We don't want a free-for-all discussion of all parts of the syntax
1319 at once; nothing will get resolved.
1320
1321 @item
1322 Whenever possible, we'll decide on policies at the highest level
1323 of abstraction.  For example, consider \numericTimeSignature,
1324 \slurUp, \xNotesOn, \startTextSpan, and \verylongfermata.  One of
1325 them starts with the name of the notation first (slur).  One has
1326 an abbreviation (x instead of cross).  One has the verb at the end
1327 (On), another has it at the beginning (start).  The adjective can
1328 come at the beginning (numeric, x) or end (Up).  Most are in
1329 camelCase, but one isn't (verylongfermata).
1330
1331 @item
1332 Instead of arguing about each individual command, we'll decide on
1333 abstract questions.  Should each command begin the notation-noun,
1334 or the verb?  Should all commands be in camelCase, or should we
1335 make everything other than articulations in camelCase but make
1336 articulations all lower-case?  Are abbreviations allowed?
1337
1338 @item
1339 Once we've answered such fundamental questions, most of the syntax
1340 should fall into place pretty easily.  There might be a few odd
1341 questions left ("is it a span, or a spanner?"), but those can be
1342 settled fairly quickly.
1343
1344 @end itemize
1345
1346 @subheading Implementation
1347
1348 Nothing until the project is finished, then we declare the next
1349 stable release (2.16.0 or 2.18.0 ?) to be the final 2.x version,
1350 release it, then apply all the GLISS syntax changes and start
1351 testing a beta for 3.0 a week or two later.
1352
1353 @subheading Discussion
1354
1355 Don't respond to any of the specifics yet.  Yes, we all have our
1356 pet irritations (like "what's up with \paper and \layout?!").
1357 There will be plenty of time to discuss them once GLISS starts.
1358
1359 That said, we have a list of specific items that people really
1360 wanted to have written down.  See @ref{Specific GLISS issues}.
1361
1362 @menu
1363 * Specific GLISS issues::
1364 @end menu
1365
1366
1367 @node Specific GLISS issues
1368 @subsection Specific GLISS issues
1369
1370 @itemize
1371 @item
1372 add regtests for every piece of syntax (not one-command-per-file,
1373 but making a few files which, between them, use every single piece
1374 of syntax.)  This is a great test for convert-ly.
1375
1376 @item
1377 should GLISS cover suggested conventions?  (indentation,
1378 one-bar-per-line, etc -- the kind of stuff we list for the
1379 lilypond formatting in the docs ?)
1380
1381 @item
1382 how much (if any) syntactic sugar should we add?  i.e.
1383 @example
1384   \instrumentName #'foo
1385 % instead of
1386   \set Staff.instrumentName
1387 @end example
1388 ?  Carl: maybe yes, Neil: no.  (for example, it fails for
1389 pianostaff)
1390
1391 @item
1392 the values that are used as arguments to common used overrides.
1393 Sometimes they are a symbol (e.g. #'around), sometimes a
1394 predefined variable referring to a Scheme value or object (e.g.
1395 #LEFT, #all-visible ). The main trouble is that for novice users
1396 it is not clear when there should be an apostrophe and when not.
1397
1398 @item
1399 When do we need -\command and when is it just \command ?
1400
1401
1402 @item
1403 Command-line options to the lilypond binary.  -dfoo counts as a
1404 tweak; we won't be trying to pin those down.
1405
1406 @item
1407 @verbatim
1408 \layout {
1409   \context { \Score
1410 % vs.
1411 \layout {
1412   \context {
1413     \Score
1414 @end verbatim
1415
1416 @item
1417 If would be pedagogically simpler to realize this difference if
1418 the syntax was separate if you define a context from scratch (as
1419 is the case with \RemoveEmptyStaffContext) or if it's defined by
1420 adding onto an existing context. For example, a syntax like
1421
1422 @verbatim
1423 \context{
1424  % Copy the current settings of the Staff context:
1425  \use Staff
1426  % do whatever additional settings
1427 }
1428 %%% could be used to distinguish from
1429 \context{
1430  % Take settings from a variable:
1431  \Variable
1432  % do whatever additional settings
1433 }
1434
1435 %%% and
1436
1437 \context{
1438  % Start from scratch:
1439  \type ...
1440  \name ...
1441  \consists ...
1442  ...
1443 }
1444 @end verbatim
1445
1446 @item
1447 Capitalization of identifiers: \VoiceOne ?
1448
1449 @item
1450 @verbatim
1451 %%% Allow
1452 { music expression } * 4
1453 %%% instead of
1454 \repeat unfold 4 { music expression }
1455 @end verbatim
1456
1457 ?  patch here:
1458 @smallexample
1459 @uref{http://lists.gnu.org/archive/html/lilypond-devel/2010-04/msg00467.html}
1460 @end smallexample
1461
1462 @item
1463 Personally, I find it easier to understand when there's a repeated
1464 8 in the half-bar position; it's much easier to see that you have
1465 two groups of 4:
1466
1467 @example
1468 c8 c c c c8 c c c
1469 %%% instead of one group of eight:
1470 c8 c c c c c c c
1471 @end example
1472
1473 @item
1474 trivially simple bar-lines:
1475
1476 c1 | c1 |
1477
1478 encourage, allow, or discourage, or disallow?
1479
1480 @item
1481 indentation of \\ inside a @{@} construct.
1482
1483
1484 @item
1485 barline checks at the end of line should be preceded by at least 2
1486 spaces?  barline checks should line up if possible (i.e.  if you
1487 can use less than 4, 8, X empty spaces before a barline check to
1488 make them line up?)
1489
1490 @item
1491 Why doesn't \transpose respect \relative mode?
1492
1493
1494 @item
1495 on \score vs. \new Score
1496
1497 But in the light of a consistent syntax and semantic, I see no
1498 reason (from the users POV) to disallow it.  After all, the real
1499 top-level context is a \book @{@}, isn't it, and I don't see a point
1500 in disallowing a \new Score construct just like \new Staff.
1501
1502 From a syntactical POV, I see the following pros for \new Score:
1503 - You can write \with @{ ... @} for every other context but \Score,
1504 which (for consistency) should also work with \new Score.
1505 - When there's a \new Foo Bar, there's also a \context Foo Bar,
1506   which makes the same as a parallel instantiation of all Bar's.
1507 - [Quoting Rune from
1508 @uref{http://www.mail-archive.com/lilypond-devel@@gnu.org/msg14713.html}
1509   "I know that the \score-statement is a syntactical construct,
1510 but I think it would be nice to hide this fact from the users.  I
1511 think we could make the use of score-block much more intuitive if
1512 changing the syntax to \new \Score and adding an implicit
1513 sequential-statement to the score."
1514
1515
1516 @item
1517 Discussion on
1518 @uref{http://code.google.com/p/lilypond/issues/detail?id=1322}
1519 about \new vs. \context.
1520
1521
1522 @item
1523 Let users add their own items to the parser?  comment 11 on:
1524 @uref{http://code.google.com/p/lilypond/issues/detail?id=1322}
1525
1526 @item
1527 should engravers be pluralized (note_heads_engraver) or not
1528 (note_head_engraver) ?
1529
1530 @item
1531 should we allow numbers in identifier names?  Issue:
1532 @uref{http://code.google.com/p/lilypond/issues/detail?id=1670}
1533
1534 @item
1535 should we officially allow accented characters?  in general, how
1536 do we feel about utf-8 stuff?
1537
1538 @item
1539 for the sake of completeness/simplicity, what about *disallowing*
1540 the "one-note" form of a music expression?  i.e. only allowing
1541 stuff like
1542 @verbatim
1543   \transpose c d { e1 }
1544   \transpose c d << e1 >>
1545 @end verbatim
1546
1547 and never allowing
1548 @verbatim
1549   \transpose c d e1
1550 @end verbatim
1551
1552 @item
1553 What should be the officially encouraged way of writing music for
1554 transposing instruments? Maybe it should be simplified?
1555 See http://lists.gnu.org/archive/html/lilypond-user/2011-07/msg00130.html
1556
1557 @end itemize
1558
1559
1560 @node Unsorted policies
1561 @section Unsorted policies
1562
1563 @subsubheading Language-specific mailing lists
1564
1565 A translator can ask for an official lilypond-xy mailing list once
1566 they've finished all @qq{priority 1} translation items.
1567
1568 @subsubheading Performing yearly copyright update (@qq{grand-replace})
1569
1570 At the start of each year, copyright notices for all source files
1571 should be refreshed by running the following command from the top of
1572 the source tree:
1573
1574 @example
1575 make grand-replace
1576 @end example
1577
1578 Internally, this invokes the script @file{scripts/build/grand-replace.py},
1579 which performs a regular expression substitution for old-year -> new-year
1580 wherever it finds a valid copyright notice.
1581
1582 Note that snapshots of third party files such as @file{texinfo.tex} should
1583 not be included in the automatic update; @file{grand-replace.py} ignores these
1584 files if they are listed in the variable @code{copied_files}.
1585
1586
1587 @subsubheading Push git access
1588
1589 Git access is given out when a contributor has a significant
1590 record of patches being accepted without problems.  If existing
1591 developers are tired of pushing patches for a contributor, we'll
1592 discuss giving them push access.  Unsolicited requests from
1593 contributors for access will almost always be turned down.
1594