1 @c -*- coding: utf-8; mode: texinfo; -*-
2 @node Administrative policies
3 @chapter Administrative policies
5 This chapter discusses miscellaneous administrative issues which
6 don't fit anywhere else.
9 * Meta-policy for this document::
11 * Administrative mailing list::
12 * Grand Organization Project (GOP)::
13 * Grand LilyPond Input Syntax Standardization (GLISS)::
17 @node Meta-policy for this document
18 @section Meta-policy for this document
20 The Contributor's Guide as a whole is still a work in progress,
21 but some chapters are much more complete than others. Chapters
22 which are @qq{almost finished} should not have major changes
23 without a discussion on @w{@code{-devel}}; in other chapters, a
24 disorganized @qq{wiki-style dump} of information is encouraged.
26 Do not change (other than spelling mistakes) without discussion:
31 @ref{Introduction to contributing}
34 @ref{Working with source code}
38 Please dump info in an appropriate @@section within these manuals,
39 but discuss any large-scale reorganization:
47 @ref{Documentation work}
53 @ref{Regression tests}
56 @ref{Programming work}
61 Totally disorganized; do whatever the mao you want:
75 @ref{Administrative policies}
84 We have four jobs for organizing a team of contributors:
89 Bug Meister: trains new Bug Squad volunteers, organizes who works
90 on which part of their job, checks to make sure that everything is
91 running smoothly, and has final say on our policy for Issues.
96 Doc Meister: trains new doc editors/writers, organizes who works
97 on which part of the job, checks to make sure that everything is
98 running smoothly, and has final say on our policy for
99 Documentation. Also includes LSR work.
104 Translation Meister: trains new translators, updates the
105 translation priority list, and handles merging branches (in both
111 Frog Meister: is responsible for code patches from (relatively)
112 inexperienced contributors. Keeps track of patches, does initial
113 reviewing of those patches, sends them to @w{@code{-devel}} when
114 they've had some initial review on the Frog list, pesters the
115 @w{@code{-devel}} community into actually reviewing said patches, and
116 finally pushes the patches once they're accepted. This person is
117 @emph{not} responsible for training new programmers, because that
118 would be far too much work -- he job is @qq{only} to guide
119 completed patches through our process.
125 @node Administrative mailing list
126 @section Administrative mailing list
128 An mailing list for administrative issues is maintained at
129 @code{lilypond-hackers@@gnu.org}.
131 This list is intended to be used for discussions that should be kept
132 private. Therefore, the archives are closed to the public.
134 Subscription to this list is limited to certain senior developers.
136 At the present time, the list is dormant.
138 Details about the criteria for membership, the types of discussion
139 to take place on the list, and other policies for the hackers list
140 will be finalized during the
141 @ref{Grand Organization Project (GOP)}.
145 @node Grand Organization Project (GOP)
146 @section Grand Organization Project (GOP)
152 Clarify the various development tasks by writing down the polices
153 and techniques and/or simplifying the tasks directly.
156 Get more people involved in development: specifically, find people
157 to do easy tasks to allow advanced developers to concentrate on
166 * Policy decisions (finished)::
170 @subsection Motivation
172 Most readers are probably familiar with the LilyPond Grand
173 Documentation Project, which ran from Aug 2007 to Aug 2008. This
174 project involved over 20 people and resulted in an almost complete
175 rewrite of the documentation. Most of those contributors were
176 normal users who decided to volunteer their time and effort to
177 improve lilypond for everybody. By any measure, it was a great
180 The Grand Organization Project aims to do the same thing with a
181 larger scope -- instead of focusing purely on documentation, the
182 project aims to improve all parts of LilyPond and its community.
183 Just as with GDP, the main goal is to encourage and train users to
184 become more involved.
186 If you have never contributed to an open-source project before --
187 especially if you use Windows or OSX and do not know how to
188 program or compile programs -- you may be wondering if there's
189 anything you can do. Rest assured that you @emph{can} help.
191 @subheading "Trickle-up" development
193 One of the reasons I'm organizing GOP is "trickle-up"
194 development. The idea is this: doing easy tasks frees up advanced
195 developers to do harder tasks. Don't ask "am I the @emph{best}
196 person for this job"; instead, ask "am I @emph{capable} of doing
197 this job, so that the current person can do stuff I @emph{can't}
200 For example, consider lilypond's poor handling of grace notes in
201 conjunction with clef and tempo changes. Fixing this will require
202 a fair amount of code rewriting, and would take an advanced
203 developer a few weeks to do. It's clearly beyond the scope of a
204 normal user, so we might as well sit back and do nothing, right?
206 No; we @emph{can} help, indirectly. Suppose that our normal user
207 starts answering more emails on lilypond-user. This in turn means
208 that documentation writers don't need to answer those emails, so
209 they can spend more time improving the docs. I've noticed that all
210 doc writers tackle harder and harder subjects, and when they start
211 writing docs on scheme programming and advanced tweaks, they start
212 contributing bug fixes to lilypond. Having people performing these
213 easy-to-moderate bug fixes frees up the advanced developers to
214 work on the really hard stuff... like rewriting the grace note
217 Having 1 more normal user answering emails on lilypond-user won't
218 have a dramatic trick-up affect all by himself, of course. But if
219 we had 8 users volunteering to answer emails, 6 users starting to
220 write documentation, and 2 users editing LSR... well, that would
221 free up a lot of current bug-fixing-capable contributors to focus
222 on that, and we could start to make a real dent in the number of
223 bugs in lilypond. Quite apart from the eased workload, having that
224 many new helpers will provide a great moral boost!
227 @subsection Ongoing jobs
229 Although GOP is a short-term project, the main goal is to train
230 more people to handle ongoing jobs. The more people doing these
231 jobs, the ligher the work will be, and the more we can get done
234 Also, it would be nice if we had at least one "replacement" /
235 "understudy" for each role -- too many tasks are only being done
236 by one person, so if that person goes on vacation or gets very
237 busy with other matters, work in that area grinds to a halt.
239 @subheading Jobs for normal users
243 LilyPond is sometimes critized for not listening to users, but
244 whenever we ask for opinions about specific issues, we never get
245 enough feedback. This is somewhat aggravating.
246 We need a group of users to make a dedicated effort to test and
247 give feedback. If there's new documentation, read it. If there's
248 an experimental binary, download it and try compiling a score with
249 it. If we're trying to name a new command, think about it and give
252 @item lilypond-user support:
253 I think it would be nice if we had an official team of users
256 @item LilyPond Report:
257 Keeping a monthly newsletter running is a non-trivial task. A lot
258 of work is needed to organize it; it would be great if we could
259 split up the work. One person could write the Snippet of the
260 Month, another person could do Quotes of the Month, another person
261 could do interviews, etc.
264 Although GDP (the Grand Documentation Project) did great work,
265 there's still many tasks remaining.
268 Keeping the documentation translations is a monumental task; we
269 need all the help we can get!
273 @subheading Jobs for advanced users for developers
276 @item Git help for writers:
277 We often receive reports of typos and minor text updates to the
278 documentation. It would be great if somebody could create
279 properly-formatted patches for these corrections.
281 Technical requirements: ability to run @ref{Lilydev}.
284 LSR contains many useful examples of lilypond, but some snippets
285 are out of date and need updating. Other snippets need to be
286 advertized, and new snippets need to be sorted. We could use
287 another person to handle LSR.
289 Technical requirements: use of a web browser. LilyPond
290 requirements: you should be familiar with most of Notation
291 chapters 1 and 2 (or be willing to read the docs to find out).
293 @item Join the Frogs:
294 "Frogs" are a team of bug-fixers (because frogs eat bugs, and you
295 often find them in Ponds of Lilies) and new feature implementors.
297 Technical requirements: development environment (such as
298 @ref{Lilydev}), ability to read+write scheme and/or C++ code.
303 @node Policy decisions
304 @subsection Policy decisions
306 There are a number of policy decisions -- some of them fairly
307 important -- which we have been postponing for a few years. We
308 are now discussing them slowly and thoroughly; agenda and exact
309 proposals are online:
312 @uref{http://lilypond.org/~graham/gop/index.html}
315 Below is a list of policies which are not @qq{on the agenda} yet.
317 Note that the presence of an item on this list does @emph{not}
318 mean that everybody thinks that something needs to be done.
319 Inclusion in this simply means that one developer thinks that we
320 should discuss it. We are not going to filter this list; if any
321 developer thinks we should discuss something, just add it to the
322 bottom of the list. (the list is unsorted)
324 As GOP progresses, items from this list will be put on the agenda
325 and removed from this list. I generally try to have one month's
326 discussion planned in advance, but I may shuffle things around to
327 respond to any immediate problems in the developer community.
329 There are some item(s) not displayed here; these are questions
330 that were posed to me privately, and I do not feel justified in
331 discussing them publicly without the consent of the person(s) that
332 brought them up. They will initially be discussed privately on the
333 lilypond-hackers mailing list -- but the first question will be
334 "do we absolutely need to do this privately", and if not, the
335 discussion will take place on lilypond-devel like the other items.
337 In most policy discussions in lilypond over the past few years,
338 the first half (or more) is wasted arguing on the basis of
339 incorrect or incomplete data; once all the relevant facts are
340 brought to light, the argument is generally resolved fairly
341 quickly. In order to keep the GOP discussions focused, each topic
342 will be introduced with a collection of relevant facts and/or
343 proposals. It is, of course, impossible to predict exactly which
344 facts will be relevant to the discussion -- but spending an hour
345 or two collecting information could still save hours of
348 @warning{The estimated time required for "prep work", and the
349 following discussion, has been added to each item. At the moment,
350 there is an estimated 30 hours of prep work and 140 hours of
354 @item @strong{Patch reviewing}:
355 At the time of this writing, we have 23 (known) patches waiting
356 for review. Some from main developers; some from new developers.
357 We desperately need more people helping with lilypond, but
358 ignoring patches is the best way to drive potential contributors
359 away. This is not good.
361 (prep: 2 hours. discuss: 10 hours)
363 @item @strong{Future release policy}:
364 (how) should we change any policies pertaining to releases? Should
365 an undocumented new feature count as release-blocking?
367 (prep: 1 hour. discuss: 15 hours)
369 @item @strong{lilypond-hackers mailing list}:
370 Should we have a private mailing list for senior developers? If
371 so, who should be on it?
373 (prep: 2 hours+3 weeks. discuss: 10 hours)
375 @item @strong{Hackers B}:
378 @item @strong{Git repository(s)}:
379 We currently have a web/ branch in our main repo; this seems
380 misleading to new developers. More generally, should we have
381 branches that aren't related to the master? i.e. should we
382 restrict a git branch to code which is an actual "branch" of
383 development? Also, some of our code (notably the windows and osx
384 lilypad) isn't in a git repository at all.
385 We can add new repositories very easily; should make repositories
388 git://git.sv.gnu.org/lilypond/gub.git
389 git://git.sv.gnu.org/lilypond/lilypad.git
390 git://git.sv.gnu.org/lilypond/misc.git
392 ? More information here:
393 @uref{http://code.google.com/p/lilypond/issues/detail?id=980}
395 (prep: 2 hours. discuss: 10 hours)
397 @item @strong{Roadmap of future development}:
398 Many projects have a roadmap of planned (or desired) future work.
399 Should we use one? If so, what should go on it, bearing in mind
400 our volunteer status? Is there any way of having a roadmap that
403 (prep: 1 hour. discuss: 5 hours)
405 @item @strong{Official links to other organizations?}:
406 There's something called the "software freedom conservancy", and
407 in general, there's a bunch of "umbrella organizations". Joining
408 some of these might give us more visibility, possibly leading to
409 more users, more developers, maybe even financial grants or use in
412 (prep: 2 hours. discuss: 5 hours)
414 @item @strong{Mailing lists}:
415 We currently have a mix of official GNU mailing lists and lilynet
416 lists. Is there a strong rationale for having separate mailing
417 list servers? Why not pick one place, and put all our lists there?
418 (or at least, all "permanent" lists?)
420 (prep: 1 hour. discuss: 5 hours)
422 @item @strong{Issue tracking with google code}:
423 We use the google issue tracker, but this means that we are
424 relying on a commercial entity for a large part of our
425 development. Would it be better (safer in the long run) to use the
426 savannah bug tracker?
428 (prep: 1 hour. discuss: 5 hours)
430 @item @strong{Patch review tool}:
431 Reitveld is inconvenient in some respects: it requires a google
432 account, and there's no way to see all patches relating to
433 lilypond. Should we switch to something like gerritt?
434 @uref{http://code.google.com/p/lilypond/issues/detail?id=1184}
436 (prep: 5 hours. discuss: 15 hours)
438 @item @strong{Subdomains of *.lilypond.org}:
439 Unless Jan has a really weird DNS hosting setup, there are no
440 technical barriers to having names like lsr.lilypond.org,
441 frog.lilypond.org, or news.lilypond.org. Is this something that we
444 (prep: 1 hours+2 weeks. discuss: 5 hours)
446 @item @strong{Authorship in source files}:
447 Our documentation currently does not attempt to track individual
448 authors of each file, while our source code makes a confused and
449 jumbled attempt to track this. A number of guidelines for F/OSS
450 projects explicitly recommends _not_ tracking this in individual
451 files, since the code repository will track that for you.
453 (prep: 2 hours. discuss: 15 hours)
455 @item @strong{Clarity for sponsorships}:
456 We currently do not advertize bounties and sponsorships on the
457 webpage. How much advertising do we want, and what type?
458 Should we change the "structure" / "framework" for bounties?
460 (prep: 2 hours. discuss: 10 hours)
462 @item @strong{Separate branches for active development}:
463 it might be good to have @emph{everybody} working on separate
464 branches. This complicates the git setup, but with sufficient
465 logic in lily-git.tcl, we can probably make it transparent to
466 newbies. However, we'd need a reliable person to handle all the
467 required merging and stuff.
469 (prep: 2 hours. discuss: 10 hours)
471 @item @strong{When do we add regtests?}:
472 There is a discrepancy between our stated policy on adding
473 regtests, and our actual practice in handling bugs and patches.
476 There is also a wider question how to organize the regtests, such
477 as where to put interesting-console-output regtests, including
478 stuff like lilypond-book and midi2ly in a sensible manner, and
479 possibly including regtests for currently-broken functionality.
481 (prep: 2 hours. discuss: 5 hours)
483 @item @strong{code readability}:
484 "Our aim when producing source code for Lilypond in whatever
485 language is that it should be totally comprehensible to a
486 relatively inexperienced developer at the second reading."
489 - aids maintainability of code base
490 - "second reading" so newer developers can look up unfamiliar
492 - will help to keep things simple, even if the code is doing
493 complex stuff discourages "secret squirrel" coding, e.g. "how
494 much functionality can I squeeze into as few characters as
495 possible" "comments are for wimps"
496 - will aid not *discouraging* new developers to join the project
498 (prep: 2 hours. discuss: 10 hours)
500 @item @strong{C++ vs. scheme}:
501 what should be in scheme, what should be in C++, what can/should
502 be ported from one to the other, etc. Questions of
503 maintainability, speed (especially considering guile 2.0), and the
504 amount of current material in either form, are important.
506 (prep: 5 hours. discuss: 15 hours)
508 @item @strong{always make an issue number for patches}:
509 there is a proposal that we should always have a google code issue
510 number for every patch. This proposal is closely tied to our
511 choice of patch review tool; if we switch to a different tool (as
512 suggested in a different proposal), this proposal may become moot.
514 (prep: 1 hour. discuss: 5 hours)
516 @item @strong{initalizer lists}:
517 shoudl we use initalizer lists for C++? AFAIK they make no
518 difference for built-in types, but there's some weird case where
519 it's more efficient for objects, or something.
521 Probably not worth making this a weekly thing on its own, but we
522 can probably wrap it up with some other code-related questions.
524 (prep: 15 minutes. discuss: 3 hours)
528 @node Policy decisions (finished)
529 @subsection Policy decisions (finished)
531 Here is a record the final decisions, along with links to the
535 * GOP-PROP 1 - python formatting::
536 * GOP-PROP 2 - mentors and frogs::
537 * GOP-PROP 3 - C++ formatting::
538 * GOP-PROP 4 - lessons from 2.14::
539 * GOP-PROP 5 - build system output (not accepted)::
540 * GOP-PROP 6 - private mailing lists::
541 * GOP-PROP 7 - developers as resources::
542 * GOP-PROP 8 - issue priorities::
543 * GOP-PROP 9 - behavior of make doc::
546 @node GOP-PROP 1 - python formatting
547 @subsubsection GOP-PROP 1 - python formatting
549 We will follow the indentation described in PEP-8.
550 @uref{http://www.python.org/dev/peps/pep-0008/}
554 use 4 spaces per indentation level
557 never mix tabs and spaces (for indentation)
560 Code indented with a mixture of tabs and spaces should be
561 converted to using spaces exclusively
563 Once this is done, we should add @code{python -tt} to the build
564 system to avoid such errors in the future.
568 There should be absolutely no tab characters for indentation in
569 any @code{.py} file in lilypond git. All such files should be
570 converted to use spaces only.
572 @subsubheading Discussions
575 @uref{https://lists.gnu.org/archive/html/lilypond-devel/2011-06/msg00060.html}
576 @uref{https://lists.gnu.org/archive/html/lilypond-devel/2011-06/msg00084.html}
577 @uref{https://lists.gnu.org/archive/html/lilypond-devel/2011-06/msg00310.html}
578 @uref{https://lists.gnu.org/archive/html/lilypond-devel/2011-06/msg00574.html}
582 @node GOP-PROP 2 - mentors and frogs
583 @subsubsection GOP-PROP 2 - mentors and frogs
585 Nothing much was decided. The list of responsibilities was
586 slightly altered; see the new one in @ref{Mentors}. We should
587 encourage more use of the Frogs mailing list. There's a list of
588 contributor-mentor pairs in:
591 @uref{https://github.com/gperciva/lilypond-extra/blob/master/people/mentors.txt}
594 That's pretty much it.
596 @subsubheading Discussions
599 @uref{https://lists.gnu.org/archive/html/lilypond-devel/2011-06/msg00311.html}
605 @node GOP-PROP 3 - C++ formatting
606 @subsubsection GOP-PROP 3 - C++ formatting
608 Speaking academically, C++ code style is a "solved problem". Let's
609 pick one of the existing solutions, and let a computer deal with
610 this. Humans should not waste their time, energy, and creativity
611 manually adding tabs or spaces to source code.
613 We have modified @code{fixcc.py} to use astyle, along with extra
618 the final script will be run @strong{blindly} on the lilypond
619 source code. We will accept whatever formatting the final version
620 of this script produces, with no manual tweaking.
623 patches which have been run through this tool will not be rejected
624 for style reasons. Any code formatting @qq{desires} which are not
625 enforced by @code{fixcc.py} will not be considered grounds for
629 for now, this style will not be enforced. It is not cause for
630 concern if patches which do not follow the formatting done by
631 @code{fixcc.py} are pushed. From time to time, Graham will run
632 the formatter on the entire code base, and commit the resulting
635 In a few months, we will tighten up this policy item (with some
636 sort of automatic processing), but that is outside the scope of
637 this policy item and is a matter for later discussion.
640 after the proposal is accepted, we will leave some time for
641 existing patches to be accepted and pushed. The script was
642 run on the source code on @strong{2011 August 01}.
648 LilyPond is a GNU project, so it makes sense to follow the GNU
649 coding standards. These standards state:
652 We don’t think of these recommendations as requirements, because
653 it causes no problems for users if two different programs have
654 different formatting styles.
656 But whatever style you use, please use it consistently, since a
657 mixture of styles within one program tends to look ugly. If you
658 are contributing changes to an existing program, please follow the
659 style of that program.
662 (@uref{http://www.gnu.org/prep/standards/html_node/Formatting.html})
664 With that in mind, we do not think that we must blindly follow the
665 formatting given by the currrent version of Emacs.
667 @subheading Implementation notes
669 We can avoid some of the style change pollution in git history by
670 ignoring whitespaces changes:
676 @subsubheading Discussions
679 @uref{https://lists.gnu.org/archive/html/lilypond-devel/2011-06/msg00526.html}
680 @uref{https://lists.gnu.org/archive/html/lilypond-devel/2011-06/msg00796.html}
681 @uref{https://lists.gnu.org/archive/html/lilypond-devel/2011-07/msg00200.html}
682 @uref{https://lists.gnu.org/archive/html/lilypond-devel/2011-07/msg00525.html}
683 @uref{https://lists.gnu.org/archive/html/lilypond-devel/2011-07/msg00751.html}
684 @uref{https://lists.gnu.org/archive/html/lilypond-devel/2011-07/msg00751.html}
688 @node GOP-PROP 4 - lessons from 2.14
689 @subsubsection GOP-PROP 4 - lessons from 2.14
693 A brief history of releases:
695 @multitable @columnfractions .2 .2 .3
696 @headitem date (YYYY-MM-DD) @tab version @tab comment
697 @item 2008-10-28 @tab 2.11.63 @tab nobody checking regtests
698 @item 2008-11-17 @tab 2.11.64
699 @item 2008-11-29 @tab 2.11.65
700 @item 2008-12-23 @tab 2.12.0
701 @item 2009-01-01 @tab @tab somewhere around here, Graham becomes
702 officially release manager, but Han-Wen still builds the actual
704 @item 2009-01-01 @tab 2.12.1
705 @item 2009-01-25 @tab 2.12.2
706 @item 2009-02-28 @tab 2.13.0
707 @item 2009-06-01 @tab 2.13.1 @tab note jump in time!
708 @item 2009-06-27 @tab 2.13.2 @tab first Graham release?
709 @item 2009-07-03 @tab 2.13.3
710 @item 2009-09-09 @tab @tab Graham arrives in Glasgow, gets a
711 powerful desktop computer, and begins serious work on GUB (sending
712 bug reports to Jan). It takes approximately 100 hours until GUB
713 is stable enough to make regular releases.
714 @item 2009-09-24 @tab 2.13.4
715 @item 2009-10-02 @tab 2.13.5
716 @item 2009-10-22 @tab 2.13.6
717 @item 2009-11-05 @tab 2.13.7
719 @item 2010-01-13 @tab 2.12.3
721 @item 2010-03-19 @tab 2.13.16 @tab Bug squad starts doing a few
722 regtest comparisons, but IIRC the effort dies out after a few
725 @item 2010-08-04 @tab 2.13.29 @tab Phil starts checking regtests (BLUE)
727 @item 2011-01-12 @tab 2.13.46 @tab release candidate 1 (GREEN)
729 @item 2011-05-30 @tab 2.13.63 @tab release candidate 7 (GREEN)
730 @item 2011-06-06 @tab 2.14.0
733 @c A graphical display of bugs:
735 @c @image{bugs-2.13-visualization,png}
736 @c @image{zoom-2.13-visualization,png}
738 @subheading Carl's analysis of the bugs
740 A @file{csv} spreadsheet is available.
743 @uref{https://lists.gnu.org/archive/html/lilypond-devel/2011-06/msg00852.html}
747 @uref{lilypond-issues-analysis.csv}
748 @uref{lilypond-issues-analysis-trim-duplicates.csv}
751 There 148 issues marked with Priority=Critical in the tracker.
753 I've done an analysis, and it looks to me like there was initially
754 a backlog of critical issues that weren't fixed, and little work
755 was being done to eliminate critical issues.
757 Somewhere about 2010-08-01, critical issues started to disappear,
758 but occasional new ones appeared.
760 There were a couple of major changes that introduced unanticipated
761 regressions (new spacing code, beam collision avoidance). These
762 produced more than the expected number of regressions.
764 It appears to me that we didn't really get serious about
765 eliminating critical bugs until about 2010-06-15 or so. After
766 that point, the number of critical bugs more-or-less steadily
767 decreased until we got to a release candidate.
769 Of particular interest, the first release candidate of 2.14 was
770 released on 2011-01-12. Over the next 10 days, about a dozen bugs
771 were reported and fixed. Release candidate 2 came out on
772 2011-02-09. No surge of bugs occurred with this release.
773 Candidate 3 came out on 2011-03-13; we got 2 bugs per week.
774 Candidate 4 came out on 2011-03-29; 2 new bugs. Candidate 6 came
775 out on 2011-04-07. We got a couple of bugs per week.
777 @subheading Notes, commentary, and opinions
780 Han-Wen: Overall, I think this cycle took too long
785 @subsubheading Discussions
788 @uref{https://lists.gnu.org/archive/html/lilypond-devel/2011-06/msg00797.html}
789 @uref{https://lists.gnu.org/archive/html/lilypond-devel/2011-07/msg00364.html}
794 @node GOP-PROP 5 - build system output (not accepted)
795 @subsubsection GOP-PROP 5 - build system output (not accepted)
797 This proposal was too broad; after a month of discussion, Graham
798 withdrew the proposal. Portions of it will be introduced in later
801 @subsubheading Discussions
804 @uref{https://lists.gnu.org/archive/html/lilypond-devel/2011-07/msg00320.html}
805 @uref{https://lists.gnu.org/archive/html/lilypond-devel/2011-07/msg00527.html}
806 @uref{https://lists.gnu.org/archive/html/lilypond-devel/2011-07/msg00753.html}
807 @uref{https://lists.gnu.org/archive/html/lilypond-devel/2011-07/msg01042.html}
808 @uref{https://lists.gnu.org/archive/html/lilypond-devel/2011-08/msg00116.html}
809 @uref{https://lists.gnu.org/archive/html/lilypond-devel/2011-08/msg00310.html}
813 @node GOP-PROP 6 - private mailing lists
814 @subsubsection GOP-PROP 6 - private mailing list
816 Potentially sensitive or private matters will be referred to
817 Graham. He will then decide who should discuss the matter on an
818 ad-hoc basis, and forward or CC them on future emails.
820 For emphasis, the project administrators are Han-Wen, Jan, and
821 Graham; those three will always be CC'd on any important
824 The lilypond-hackers mailing list will be removed.
828 There is some unhappy history about this idea in our development
832 @uref{http://lists.gnu.org/archive/html/lilypond-devel/2010-09/msg00178.html}
833 @uref{http://news.lilynet.net/spip.php?article121}
834 @uref{http://lists.gnu.org/archive/html/lilypond-devel/2010-11/msg00076.html}
837 @subheading Other projects
839 The idea of private mailing lists is hardly uncommon in
840 open-source software. For example,
843 @uref{http://lwn.net/Articles/394660/} about debian-private
844 @uref{http://subversion.apache.org/mailing-lists.html} private@@
845 @uref{http://www.freebsd.org/administration.html#t-core}
846 @uref{http://foundation.gnome.org/legal/} board members pledge
847 to keep certain matters confidential
849 every security team of every linux distribution and OS
852 In fact, Karl Fogel's @qq{Producing Open Source Software}
853 explicitly suggests a private mailing list for some circumstances:
856 [on granting commit/push access to a contributor]
858 But here is one of the rare instances where secrecy is
859 appropriate. You can't have votes about potential committers
860 posted to a public mailing list, because the candidate's feelings
861 (and reputation) could be hurt.
863 @uref{http://producingoss.com/en/consensus-democracy.html#electorate}
866 @subheading Board of governers, voting, etc?
868 Many projects have an official board of directors, or a list of
869 @qq{core developers}, with set term limits and elections and
872 I don't think that we're that big. I think we're still small
873 enough, and there's enough trust and consensus decisions, that we
874 can avoid that. I would rather that we kept on going with
875 trust+consensus for at least the next 2-3 years, and spent more
876 time+energy on bug fixes and new features instead of
877 administrative stuff.
879 Project administrators are Han-Wen, Jan, and Graham.
881 @subsubheading Discussions
884 @uref{https://lists.gnu.org/archive/html/lilypond-devel/2011-07/msg00783.html}
885 @uref{https://lists.gnu.org/archive/html/lilypond-devel/2011-07/msg01004.html}
886 @uref{https://lists.gnu.org/archive/html/lilypond-devel/2011-08/msg00117.html}
890 @node GOP-PROP 7 - developers as resources
891 @subsubsection GOP-PROP 7 - developers as resources
893 We shall treat developers (and contributors) as
894 @strong{Independent volunteers}: each person does whatever they
895 want, whenever they want. We have busy careers and lives; we make
896 no expectations of action from anybody (with the exception of the
897 6 people in @qq{Meister} positions).
899 @subsubheading Discussions
902 @uref{https://lists.gnu.org/archive/html/lilypond-devel/2011-07/msg01092.html}
903 @uref{https://lists.gnu.org/archive/html/lilypond-devel/2011-08/msg00087.html}
904 @uref{https://lists.gnu.org/archive/html/lilypond-devel/2011-08/msg00497.html}
908 @node GOP-PROP 8 - issue priorities
909 @subsubsection GOP-PROP 8 - issue priorities
911 We will delete the @qq{priority} field of the issue tracker
912 altogether. The @qq{type} system will be tweaked.
919 a reproducible failure to build either @code{make} or @code{make
920 doc}, from an empty build tree, in a first run, if
921 @code{configure} does not report any errors.
924 any program behaviour which is @strong{unintentionally} worse than
925 the previous stable version or the current development version.
926 Developers may always use the @qq{this is intentional}, or even
927 the @qq{this is an unavoidable effect of an improvement in another
928 area}, reason to move this to a different type.
931 anything which stops contributors from helping out (e.g.
932 lily-git.tcl not working, source tree(s) not being available,
933 lilydev being unable to compile git master, inaccurate
934 instructions in the Contributor's Guide 2 Quick start).
936 To limit this scope of this point, we will assume that the
937 contributor is using the latest lilydev and has read the relevant
938 part(s) of the Contributor's Guide. Problems in other chapters of
939 the CG are not sufficient to qualify as Type-Critical.
943 @subsubheading More new/changed types and labels
945 Unless otherwise specified, the current types and labels will
946 continue to be used. The new types introduced by this proposal
952 Type-crash: any segfault, regardless of what the input file looks
953 like or which options are given. Disclaimer: this might not be
954 possible in some cases, for example certain guile programs (we
955 certainly can't predict if a piece of scheme will ever stop
956 running, i.e. the halting problem), or if we rely on other
957 programs (i.e. ghostscript). If there are any such cases that
958 make segfault-prevention impossible, we will document those
959 exceptions (and the issue will remain as a "crash" instead of
960 "documentation" until the warning has been pushed).
963 Type-maintainability: anything which makes it difficult for
964 serious contributors to help out (e.g. difficult to find the
965 relevant source tree(s), confusing policies, problems with
966 automatic indentation tools, etc).
969 Type-ugly: replaces Type-collision, and it will include things
970 like bad slurs in addition to actual collision.
974 A new label will be added:
978 (label) Needs_evidence: it is not clear what the correct output
979 should look like. We need scans, references, examples, etc.
983 @subheading Reminding users about stars
985 We can remind users that they can @qq{star} an issue to indicate
986 that they care about it. Since we resolved to treat developers as
987 independent volunteers, there is no expectation that anybody will
988 look at those stars, but if any developer want to organize their
989 work schedule according to the stars, they are welcome to do so.
991 @subsubheading Discussions
994 @uref{https://lists.gnu.org/archive/html/lilypond-devel/2011-08/msg00019.html}
995 @uref{https://lists.gnu.org/archive/html/lilypond-devel/2011-08/msg00277.html}
996 @uref{https://lists.gnu.org/archive/html/lilypond-devel/2011-08/msg00413.html}
997 @uref{https://lists.gnu.org/archive/html/lilypond-devel/2011-08/msg00624.html}
1002 @node GOP-PROP 9 - behavior of make doc
1003 @subsubsection GOP-PROP 9 - behavior of make doc
1005 If there are build problems, then it should be easier to find out
1006 why it's failing. This will be achieved with log files, as well
1007 as possibly including scripts which automatically display portions
1008 of those log files for a failing build.
1010 We will also add targets for building a specific manual (for
1011 quick+easy checking of doc work), as well as for building all
1012 documentation in a specific language (either English or a
1013 translated language).
1015 When you run @code{make doc},
1020 All output will be saved to various log files, with the exception
1021 of output directly from @code{make(1)}.
1023 Note that @code{make(1)} refers to a specific executable file on
1024 unix computers, and is not a general term for the build system.
1027 By default, no other output will be displayed on the console, with
1028 one exception: if a build fails, we might display some portion(s)
1029 of log file(s) which give useful clues about the reason for the
1032 The user may optionally request additional output to be printed;
1033 this is controlled with the @code{VERBOSE=x} flag. In such cases,
1034 all output will still be written to log files; the console output
1035 is strictly additional to the log files.
1038 Logfiles from calling lilypond (as part of lilypond-book) will go
1039 in the relevant @file{build/out/lybook-db/12/lily-123456.log}
1040 file. All other logfiles will go in the @file{build/logfiles/}
1043 A single @code{make doc} will therefore result in hundreds of log
1044 files. Log files produced from individual lilypond runs are not
1045 under our control; apart from that, I anticipate having one or two
1046 dozen log files. As long as it is clear which log file is
1047 associated with which operation(s), I think this is entirely
1048 appropriate. The precise implementation will be discussed for
1049 specific patches as they appear.
1052 Both stderr and stdout will be saved in @code{*.log}. The order
1053 of lines from these streams should be preserved.
1056 There will be no additional @qq{progress messages} during the
1057 build process. If you run @code{make --silent}, a non-failing
1058 build should print absolutely nothing to the screen.
1061 Assuming that the loglevels patch is accepted, lilypond (inside
1062 lilypond-book) will be run with --loglevel=WARN.
1063 @uref{http://codereview.appspot.com/4822055/}
1066 Ideally, a failing build should provide hints about the reason why
1067 it failed, or at least hints about which log file(s) to examine.
1071 If this proposal is accepted, none of these policies will be
1072 assumed to apply to any other aspect of the build system.
1073 Policies for any other aspect of the build system will be
1074 discussed in separate proposals.
1076 @subheading Don't cause more build problems
1078 However, there is a danger in this approach, that vital error
1079 messages can also be lost, thus preventing the cause of the
1080 failure of a make being found. We therefore need to be
1081 exceptionally careful to move cautiously, include plenty of tests,
1082 and give time for people to experiment/find problems in each stage
1083 before proceeding to the next stage.
1085 This will be done by starting from individual lilypond calls
1086 within lilypond-book, and slowly moving to @qq{larger} targets of
1087 the build system -- after the individual lilypond calls are are
1088 producing the appropriate amount of output and this is saved in
1089 the right place and we can automatically isolate parts of a
1090 failing build, we will work on lilypond-book in general, and only
1091 then will we look at the build system itself.
1093 @subheading Implementation notes
1095 There is an existing make variable QUIET_BUILD, which
1096 alter the amount of output being displayed
1098 http://lilypond.org/doc/v2.15/Documentation/contributor/useful-make-variables}
1099 ). We are not planning on keeping this make variable.
1101 The standard way for GNU packages to give more output is with a
1102 @code{V=x} option. Presumably this is done by increasing
1103 @code{x}? If we support this option, we should still write log
1104 files; we would simply print more of the info in those log files
1107 The command @code{tee} may be useful to write to a file and
1108 display to stdout (in the case of VERBOSE).
1111 @subsubheading Discussions
1114 @uref{https://lists.gnu.org/archive/html/lilypond-devel/2011-08/msg00378.html}
1115 @uref{https://lists.gnu.org/archive/html/lilypond-devel/2011-08/msg00703.html}
1120 @n ode GOP-PROP 10 - scheme indentation
1121 @s ubsubsection GOP-PROP 10 - scheme indentation
1123 still under discussion
1125 @subsubheading Discussions
1128 @uref{https://lists.gnu.org/archive/html/lilypond-devel/2011-08/msg00625.html}
1129 @uref{https://lists.gnu.org/archive/html/lilypond-devel/2011-08/msg01026.html}
1136 @node Grand LilyPond Input Syntax Standardization (GLISS)
1137 @section Grand LilyPond Input Syntax Standardization (GLISS)
1143 Start: sortly after 2.14 comes out, which is currently estimated
1144 to happen in January 2011.
1147 Length: 6-12 months. We're not going to rush this.
1150 Goal: define an input which we commit to being
1151 machine-updateable for the forseeable future. Any future patches
1152 which change the syntax in a non-convert-ly-able format will be
1153 rejected. (subject to the limitations, below)
1154 Once this is finished, we will release lilypond 3.0.
1159 @subheading The Problem
1161 One of the biggest complaints people have with lilypond -- other
1162 than silly thing like "there's no gui" -- is the changing syntax.
1163 Now, inventing a language or standards is difficult. If you set
1164 it in stone too soon, you risk being stuck with decisions which
1165 may limit matters. If you keep on updating the syntax,
1166 interaction with older data (and other programs!) becomes complex.
1168 @subheading Scope and Limitations
1172 tweaks will not be included. Anything with \override, \set,
1173 \overrideProperty, \tweak, \revert, \unset... including even those
1174 command names themselves... is still fair game for NOT_SMART
1178 other than that, everything is on the table. Is it a problem to
1179 have the tagline inside \header? What should the default behavior
1180 of \include be? When we abolish \times, do we move to \tuplet 3:2
1181 or \tuplet 2/3 or what (for typical triplets in 4/4 time)?
1184 we need to get standards for command names. This will help users
1185 remember them, and reduce the options for future names (and
1186 potential renamings later on). \commandOn and \commandOff seem to
1187 work well (should we *always* have an Off command?), but what
1188 about the "command" part? Should it be \nounVerbOn, or
1189 \verbNounOn ? Or \verbNotesWithExtraInformationOn ?
1192 we need standards for the location of commands. Ligature
1193 brackets, I'm looking at you. (non-postfix notation must die!)
1196 this Grand Project doesn't affect whether we have a 2.16 or not.
1197 The main problem will be deciding what to do (with a bit of
1198 messiness anticipated for \tuplet); we should definitely release a
1199 2.16 before merging _any_ of these changes.
1202 we obviously can't /guarantee/ that we'll /never/ make any
1203 non-convert-ly changes in the basic format. But we *can*
1204 guarantee that such changes would force lilypond 4.0, and that we
1205 would only do so for overwhelmingly good reasons.
1209 @subheading Workflow
1213 We're going to have lots and lots of emails flying around. The
1214 vast majority won't really fit into either -devel or -user, so
1215 we'll use a list devoted to syntax issues.
1218 Once we have a serious proposal that gained general acceptance
1219 from the separate syntax mailing list, I'll bring it to -devel.
1220 We're not going to make any changes without discussing it on
1221 -devel, but if we're going to have huge threads about English
1222 grammar and silly ideas, and I don't want to clutter up -devel.
1223 Once whatever chaotic silliness on the syntax list is settled
1224 down, I'll bring the ideas to -devel.
1227 as with GDP, I'll moderate the discussion. Not as with mailist
1228 moderation, but rather by introducing issues at specific times.
1229 We don't want a free-for-all discussion of all parts of the syntax
1230 at once; nothing will get resolved.
1233 Whenever possible, we'll decide on policies at the highest level
1234 of abstraction. For example, consider \numericTimeSignature,
1235 \slurUp, \xNotesOn, \startTextSpan, and \verylongfermata. One of
1236 them starts with the name of the notation first (slur). One has
1237 an abbreviation (x instead of cross). One has the verb at the end
1238 (On), another has it at the beginning (start). The adjective can
1239 come at the beginning (numeric, x) or end (Up). Most are in
1240 camelCase, but one isn't (verylongfermata).
1243 Instead of arguing about each individual command, we'll decide on
1244 abstract questions. Should each command begin the notation-noun,
1245 or the verb? Should all commands be in camelCase, or should we
1246 make everything other than articulations in camelCase but make
1247 articulations all lower-case? Are abbreviations allowed?
1250 Once we've answered such fundamental questions, most of the syntax
1251 should fall into place pretty easily. There might be a few odd
1252 questions left ("is it a span, or a spanner?"), but those can be
1253 settled fairly quickly.
1257 @subheading Implementation
1259 Nothing until the project is finished, then we declare the next
1260 stable release (2.16.0 or 2.18.0 ?) to be the final 2.x version,
1261 release it, then apply all the GLISS syntax changes and start
1262 testing a beta for 3.0 a week or two later.
1264 @subheading Discussion
1266 Don't respond to any of the specifics yet. Yes, we all have our
1267 pet irritations (like "what's up with \paper and \layout?!").
1268 There will be plenty of time to discuss them once GLISS starts.
1270 That said, we have a list of specific items that people really
1271 wanted to have written down. See @ref{Specific GLISS issues}.
1274 * Specific GLISS issues::
1278 @node Specific GLISS issues
1279 @subsection Specific GLISS issues
1283 add regtests for every piece of syntax (not one-command-per-file,
1284 but making a few files which, between them, use every single piece
1285 of syntax.) This is a great test for convert-ly.
1288 should GLISS cover suggested conventions? (indentation,
1289 one-bar-per-line, etc -- the kind of stuff we list for the
1290 lilypond formatting in the docs ?)
1293 how much (if any) syntactic sugar should we add? i.e.
1295 \instrumentName #'foo
1297 \set Staff.instrumentName
1299 ? Carl: maybe yes, Neil: no. (for example, it fails for
1303 the values that are used as arguments to common used overrides.
1304 Sometimes they are a symbol (e.g. #'around), sometimes a
1305 predefined variable referring to a Scheme value or object (e.g.
1306 #LEFT, #all-visible ). The main trouble is that for novice users
1307 it is not clear when there should be an apostrophe and when not.
1310 When do we need -\command and when is it just \command ?
1314 Command-line options to the lilypond binary. -dfoo counts as a
1315 tweak; we won't be trying to pin those down.
1328 If would be pedagogically simpler to realize this difference if
1329 the syntax was separate if you define a context from scratch (as
1330 is the case with \RemoveEmptyStaffContext) or if it's defined by
1331 adding onto an existing context. For example, a syntax like
1335 % Copy the current settings of the Staff context:
1337 % do whatever additional settings
1339 %%% could be used to distinguish from
1341 % Take settings from a variable:
1343 % do whatever additional settings
1349 % Start from scratch:
1358 Capitalization of identifiers: \VoiceOne ?
1363 { music expression } * 4
1365 \repeat unfold 4 { music expression }
1370 @uref{http://lists.gnu.org/archive/html/lilypond-devel/2010-04/msg00467.html}
1374 Personally, I find it easier to understand when there's a repeated
1375 8 in the half-bar position; it's much easier to see that you have
1380 %%% instead of one group of eight:
1385 trivially simple bar-lines:
1389 encourage, allow, or discourage, or disallow?
1392 indentation of \\ inside a @{@} construct.
1396 barline checks at the end of line should be preceded by at least 2
1397 spaces? barline checks should line up if possible (i.e. if you
1398 can use less than 4, 8, X empty spaces before a barline check to
1402 Why doesn't \transpose respect \relative mode?
1406 on \score vs. \new Score
1408 But in the light of a consistent syntax and semantic, I see no
1409 reason (from the users POV) to disallow it. After all, the real
1410 top-level context is a \book @{@}, isn't it, and I don't see a point
1411 in disallowing a \new Score construct just like \new Staff.
1413 From a syntactical POV, I see the following pros for \new Score:
1414 - You can write \with @{ ... @} for every other context but \Score,
1415 which (for consistency) should also work with \new Score.
1416 - When there's a \new Foo Bar, there's also a \context Foo Bar,
1417 which makes the same as a parallel instantiation of all Bar's.
1418 - [Quoting Rune from
1419 @uref{http://www.mail-archive.com/lilypond-devel@@gnu.org/msg14713.html}
1420 "I know that the \score-statement is a syntactical construct,
1421 but I think it would be nice to hide this fact from the users. I
1422 think we could make the use of score-block much more intuitive if
1423 changing the syntax to \new \Score and adding an implicit
1424 sequential-statement to the score."
1429 @uref{http://code.google.com/p/lilypond/issues/detail?id=1322}
1430 about \new vs. \context.
1434 Let users add their own items to the parser? comment 11 on:
1435 @uref{http://code.google.com/p/lilypond/issues/detail?id=1322}
1438 should engravers be pluralized (note_heads_engraver) or not
1439 (note_head_engraver) ?
1442 should we allow numbers in identifier names? Issue:
1443 @uref{http://code.google.com/p/lilypond/issues/detail?id=1670}
1446 should we officially allow accented characters? in general, how
1447 do we feel about utf-8 stuff?
1450 for the sake of completeness/simplicity, what about *disallowing*
1451 the "one-note" form of a music expression? i.e. only allowing
1454 \transpose c d { e1 }
1455 \transpose c d << e1 >>
1464 What should be the officially encouraged way of writing music for
1465 transposing instruments? Maybe it should be simplified?
1466 See http://lists.gnu.org/archive/html/lilypond-user/2011-07/msg00130.html
1471 @node Unsorted policies
1472 @section Unsorted policies
1474 @subsubheading Language-specific mailing lists
1476 A translator can ask for an official lilypond-xy mailing list once
1477 they've finished all @qq{priority 1} translation items.
1479 @subsubheading Performing yearly copyright update (@qq{grand-replace})
1481 At the start of each year, copyright notices for all source files
1482 should be refreshed by running the following command from the top of
1489 Internally, this invokes the script @file{scripts/build/grand-replace.py},
1490 which performs a regular expression substitution for old-year -> new-year
1491 wherever it finds a valid copyright notice.
1493 Note that snapshots of third party files such as @file{texinfo.tex} should
1494 not be included in the automatic update; @file{grand-replace.py} ignores these
1495 files if they are listed in the variable @code{copied_files}.
1498 @subsubheading Push git access
1500 Git access is given out when a contributor has a significant
1501 record of patches being accepted without problems. If existing
1502 developers are tired of pushing patches for a contributor, we'll
1503 discuss giving them push access. Unsolicited requests from
1504 contributors for access will almost always be turned down.