1 @node Administrative policies
2 @chapter Administrative policies
4 This chapter discusses miscellaneous administrative issues which
5 don't fit anywhere else.
8 * Meta-policy for this document::
9 * Environment variables::
11 * Managing Staging and Master branches with Patchy::
12 * Administrative mailing list::
13 * Grand Organization Project (GOP)::
14 * Grand LilyPond Input Syntax Standardization (GLISS)::
18 @node Meta-policy for this document
19 @section Meta-policy for this document
21 The Contributor's Guide as a whole is still a work in progress,
22 but some chapters are much more complete than others. Chapters
23 which are @qq{almost finished} should not have major changes
24 without a discussion on @w{@code{-devel}}; in other chapters, a
25 disorganized @qq{wiki-style dump} of information is encouraged.
27 Do not change (other than spelling mistakes) without discussion:
32 @ref{Introduction to contributing}
35 @ref{Working with source code}
39 Please dump info in an appropriate @@section within these manuals,
40 but discuss any large-scale reorganization:
48 @ref{Documentation work}
54 @ref{Regression tests}
57 @ref{Programming work}
62 Totally disorganized; do whatever the mao you want:
76 @ref{Administrative policies}
81 @node Environment variables
82 @section Environment variables
84 Some maintenance scripts and instructions in this guide rely on
85 the following environment variables. They should be predefined in
86 LilyDev distribution (see @ref{LilyDev}); if you set up your own
87 development environment, you can set them by appending these settings to
88 your @file{~/.bashrc} (or whatever defines your default environment
89 variables for the user account for LilyPond development), then logging
90 out and in (adapt directories to your setup):
93 LILYPOND_GIT=~/lilypond-git
95 LILYPOND_BUILD_DIR=~/lilypond-git/build
96 export LILYPOND_BUILD_DIR
99 The standard build and install procedure (with @code{autogen.sh},
100 @code{configure}, @code{make}, @code{make install}, @code{make doc}
101 @dots{}) does not rely on them.
103 In addition, for working on the website, @code{LILYPOND_WEB_MEDIA_GIT}
104 should be set to the repository lilypond-extra, see
105 @ref{lilypond-extra}.
111 We have four jobs for organizing a team of contributors:
116 Bug Meister: trains new Bug Squad volunteers, organizes who works
117 on which part of their job, checks to make sure that everything is
118 running smoothly, and has final say on our policy for Issues.
123 Doc Meister: trains new doc editors/writers, organizes who works
124 on which part of the job, checks to make sure that everything is
125 running smoothly, and has final say on our policy for
126 Documentation. Also includes LSR work.
131 Translation Meister: trains new translators, updates the
132 translation priority list, and handles merging branches (in both
140 @node Managing Staging and Master branches with Patchy
141 @section Managing Staging and Master branches with Patchy
144 The script 'test-patches.py' no longer works with code.google.com since
145 Google changed their authentication method.
149 * Overview of Patchy::
150 * Patchy requirements::
151 * Installing Patchy::
152 * Configuring Patchy::
153 * Running the script::
154 * Automating Patchy::
155 * Troubleshooting Patchy::
158 @node Overview of Patchy
159 @subsection Overview of Patchy
161 No programmatic skill is required to run Patchy; although knowledge of
162 compiling LilyPond and its documentation along with understanding how to
163 configure the @var{PATH} environment of your computer is required. See
164 @ref{Working with source code}.
166 The script @code{lilypond-patchy-staging.py} checks for any new commits
167 in @code{remote/origin/staging}, makes sure that the new HEAD compiles
168 along with all the LilyPond documentation. Then finally pushing to
169 @code{remote/origin/master}. This script can be run and left
170 unattended, requiring no human intervention.
172 Patchy can also be configured to send emails after each successful (or
173 unsuccessful) operation. This is not a requirement and is turned off
176 @c Need to explain in more detail how to set up Patchy for email but
177 @c as I don't use myself it I have no experience - JL
180 @node Patchy requirements
181 @subsection Patchy requirements
186 A full local copy of the source code. See
187 @ref{Working with source code}.
190 All the software needed for compiling LilyPond @emph{and} the
191 documentation. Unlike testing patches, being able to build the full set
192 of LilyPond's documentation is required to be able to test & push new
193 commits. See @ref{Compiling}.
196 Commit access @emph{is} required to test and push new commits, but a
197 valid login to @uref{http://code.google.com/} is @emph{not}. See
203 @node Installing Patchy
204 @subsection Installing Patchy
206 The Patchy scripts are not part of the LilyPond code base, but can be
207 downloaded from @uref{https://github.com/gperciva/lilypond-extra/}. The
208 scripts and related Python libraries are all located in the
209 @file{patches/} directory.
211 Alternatively, use @code{git clone};
214 git clone https://github.com/gperciva/lilypond-extra/
217 This makes it simpler to update the scripts if any changes are ever made
218 to them. Finally, add the location of the @file{patches/} directory to
222 @node Configuring Patchy
223 @subsection Configuring Patchy
225 @warning{It is recommended to create a new user on your computer
226 specifically to run the Patchy scripts as a security precaution and that
227 this user should not have any administrative privileges. Also do not
228 set password protection for your ssh key else you will not be able to
229 run the scripts unattended.}
234 Make sure the environment variables @var{LILYPOND_GIT} and
235 @var{LILYPOND_BUILD_DIR} are configured appropriately. See
236 @ref{Environment variables}.
239 Manually run either the @code{lilypond-patchy-staging.py} script and
243 Warning: using default config; please edit /home/joe/.lilypond-patchy-config
244 Are you sure that you want to continue with the default config? (y/[n])
247 Answer @qq{@code{n}} and press enter.
249 The next time either of the scripts are run they will use the
250 @code{.lilypond-patchy-config} settings copied to your @code{$HOME}
254 Manually edit the @file{.lilypond-patchy-config} file, located in your
255 @code{$HOME} directory to change any of the default settings.
264 All @code{make} operations are run with;
266 extra_make_options = -j3 CPU_COUNT=3
269 See @ref{Saving time with the -j option}
272 A complete build of all the LilyPond documentation is @emph{not}
275 patch_test_build_docs = no
279 Each instance of either a patch test or commit test & push is logged in;
281 auto_compile_results_dir = ~/lilypond-auto-compile-results/
285 Both scripts will perform their build operations in;
287 build_dir = /tmp/lilypond-autobuild/
292 The script creates a clones of @code{staging} and @code{master}
293 branches (prefixed with @code{test-}) with a third branch, called
294 @code{test-master-lock} used as a check to protect against two or more
295 instances of Patchy being run locally at the same time.
298 @node Running the script
299 @subsection Running the script
301 @code{lilypond-patchy-staging.py} is run @emph{without} any arguments.
302 It then checks to see if @code{remote/origin/staging} is
303 @qq{further ahead} than @code{remote/origin/master}.
306 If there are no new differences between the two branches since the last
307 run check, the script will report something like this:
310 (UTC) Begin LilyPond compile, previous commit at 4726764cb591f622e7893407db0e7d42bcde90d9
311 Success: No new commits in staging
315 If there are any differences between the two branches since the last
316 run check, (or if the script cannot for any reason, locate the last
317 instance of a commit that it checked) it will report something like
321 (UTC) Begin LilyPond compile, previous commit at 4726764cb591f622e7893407db0e7d42bcde90d9
322 Merged staging, now at: 79e98a773b6570cfa28a15775a9dea3d3e54d6b5
323 Success: ./autogen.sh --noconfigure
324 Success: /tmp/lilypond-autobuild/configure --disable-optimising
328 and proceed with running @code{make}, @code{make test} and a
329 @code{make doc}. Unlike @code{test-patches.py} if all the tests pass,
330 the script then pushes the changes to @code{remote/origin/master}.
334 Success: nice make clean
335 Success: nice make -j7 CPU_COUNT=7
336 Success: nice make test -j7 CPU_COUNT=7
337 Success: nice make doc -j7 CPU_COUNT=7
338 To ssh://joe@@git.sv.gnu.org/srv/git/lilypond.git
339 79e98a7..4726764 test-staging -> master
340 Success: pushed to master
343 @warning{In the case where any of the @code{lilypond-patchy-staging.py}
344 tests fail, do not try to push your own fixes but report the failures to
345 the Developers List <lilypond-devel@@gnu.org> for advice.}
348 @node Automating Patchy
349 @subsection Automating Patchy
351 To run as a cron job make sure you have;
355 notify_non_action = no
358 in @file{$HOME/.lilypond-patchy-config} to avoid any unintentional email
361 Assuming that Patchy run a user @qq{patchy}, create a file called
362 @file{$HOME/lilypond-patchy.cron}, adapting it as necessary (the
363 @code{/2} means @qq{run this every 2 hours}):
366 02 0-23/2 * * * /home/patchy/lilypond-extra/patches/lilypond-patchy-staging.py
369 @warning{@code{cron} will not inherit environment variables so you must
370 re-define any variables inside @file{$HOME/lilypond-patchy.cron}. For
371 instance, @var{LILYPOND_GIT} may need to be defined if
372 @var{git_repository_dir} is not correctly set in
373 @file{$HOME/.lilypond-patchy-config}.}
375 Finally, apply the cron job (you may need superuser privileges for
379 crontab -u patchy /home/patchy/lilypond-patchy.cron
383 @node Troubleshooting Patchy
384 @subsection Troubleshooting Patchy
386 The following is a list of the most common messages that the scripts
387 may report with explanations.
390 this Git revision has already been pushed by an operator other than this Patchy.
396 Another, remote, machine has already tested and pushed the new commits
400 You may also see this if the auto-build files have been deleted and this
401 computer has previously already pushed the listed commit ID to
407 test-master-lock and PID entry exist but previous Patchy
408 run (PID xxxxx) died, resetting test-master-lock anyway.
412 A previous attempt was unsuccessful for some reason and the scripts were
413 not able to tidy up after themselves (for example if you manually halt
414 the process by killing it or closing the terminal you may have been
415 running the script in). The @code{test-master-lock} branch was
416 therefore not able to be deleted cleanly however, nothing needs to be
417 done the scripts will rebuild any tests it needs to.
420 fatal: A branch named 'test-master-lock' already exists.
426 There is another instance of Patchy running on your computer that is
427 testing the same tracker issue.
430 A previous test attempt was unsuccessful for some reason and the scripts
431 were not able to tidy up after themselves (for example if you manually
432 halt the testing process by killing it or closing the terminal you may
433 have been running the script in). The @code{test-master-lock} branch
434 was therefore not able to be deleted cleanly, in this case you must
435 manually delete the @code{test-master-lock} branch in your
436 @code{$LILYPOND_GIT} directory.
439 git branch -d test-master-lock
443 It may be wise to also manually delete @code{test-master} and
444 @code{test-staging} too, just to be safe.
451 Another instance (PID xxxxx) is already running.
455 This occurs when trying to run @code{lilypond-patchy-staging.py} when
456 another instance of either script is already running locally.
461 @node Administrative mailing list
462 @section Administrative mailing list
464 A mailing list for administrative issues is maintained at
465 @code{lilypond-hackers@@gnu.org}.
467 This list is intended to be used for discussions that should be kept
468 private. Therefore, the archives are closed to the public.
470 Subscription to this list is limited to certain senior developers.
472 At the present time, the list is dormant.
474 Details about the criteria for membership, the types of discussion
475 to take place on the list, and other policies for the hackers list
476 will be finalized during the
477 @ref{Grand Organization Project (GOP)}.
481 @node Grand Organization Project (GOP)
482 @section Grand Organization Project (GOP)
488 Clarify the various development tasks by writing down the policies
489 and techniques and/or simplifying the tasks directly.
492 Get more people involved in development: specifically, find people
493 to do easy tasks to allow advanced developers to concentrate on
502 * Policy decisions (finished)::
506 @subsection Motivation
508 Most readers are probably familiar with the LilyPond Grand
509 Documentation Project, which ran from Aug 2007 to Aug 2008. This
510 project involved over 20 people and resulted in an almost complete
511 rewrite of the documentation. Most of those contributors were
512 normal users who decided to volunteer their time and effort to
513 improve lilypond for everybody. By any measure, it was a great
516 The Grand Organization Project aims to do the same thing with a
517 larger scope -- instead of focusing purely on documentation, the
518 project aims to improve all parts of LilyPond and its community.
519 Just as with GDP, the main goal is to encourage and train users to
520 become more involved.
522 If you have never contributed to an open-source project before --
523 especially if you use Windows or OSX and do not know how to
524 program or compile programs -- you may be wondering if there's
525 anything you can do. Rest assured that you @emph{can} help.
527 @subheading "Trickle-up" development
529 One of the reasons I'm organizing GOP is "trickle-up"
530 development. The idea is this: doing easy tasks frees up advanced
531 developers to do harder tasks. Don't ask "am I the @emph{best}
532 person for this job"; instead, ask "am I @emph{capable} of doing
533 this job, so that the current person can do stuff I @emph{can't}
536 For example, consider lilypond's poor handling of grace notes in
537 conjunction with clef and tempo changes. Fixing this will require
538 a fair amount of code rewriting, and would take an advanced
539 developer a few weeks to do. It's clearly beyond the scope of a
540 normal user, so we might as well sit back and do nothing, right?
542 No; we @emph{can} help, indirectly. Suppose that our normal user
543 starts answering more emails on lilypond-user. This in turn means
544 that documentation writers don't need to answer those emails, so
545 they can spend more time improving the docs. I've noticed that all
546 doc writers tackle harder and harder subjects, and when they start
547 writing docs on scheme programming and advanced tweaks, they start
548 contributing bug fixes to lilypond. Having people performing these
549 easy-to-moderate bug fixes frees up the advanced developers to
550 work on the really hard stuff... like rewriting the grace note
553 Having 1 more normal user answering emails on lilypond-user won't
554 have a dramatic @q{trickle-up} effect all by itself, of course. But if
555 we had 8 users volunteering to answer emails, 6 users starting to
556 write documentation, and 2 users editing LSR... well, that would
557 free up a lot of current bug-fixing-capable contributors to focus
558 on that, and we could start to make a real dent in the number of
559 bugs in lilypond. Quite apart from the eased workload, having that
560 many new helpers will provide a great moral boost!
563 @subsection Ongoing jobs
565 Although GOP is a short-term project, the main goal is to train
566 more people to handle ongoing jobs. The more people doing these
567 jobs, the lighter the work will be, and the more we can get done
570 Also, it would be nice if we had at least one "replacement" /
571 "understudy" for each role -- too many tasks are only being done
572 by one person, so if that person goes on vacation or gets very
573 busy with other matters, work in that area grinds to a halt.
575 @subheading Jobs for normal users
579 LilyPond is sometimes critized for not listening to users, but
580 whenever we ask for opinions about specific issues, we never get
581 enough feedback. This is somewhat aggravating.
582 We need a group of users to make a dedicated effort to test and
583 give feedback. If there's new documentation, read it. If there's
584 an experimental binary, download it and try compiling a score with
585 it. If we're trying to name a new command, think about it and give
588 @item lilypond-user support:
589 I think it would be nice if we had an official team of users
592 @item LilyPond Report:
593 Keeping a monthly newsletter running is a non-trivial task. A lot
594 of work is needed to organize it; it would be great if we could
595 split up the work. One person could write the Snippet of the
596 Month, another person could do Quotes of the Month, another person
597 could do interviews, etc.
600 Although GDP (the Grand Documentation Project) did great work,
601 there's still many tasks remaining.
604 Keeping the documentation translations is a monumental task; we
605 need all the help we can get!
609 @subheading Jobs for advanced users for developers
612 @item Git help for writers:
613 We often receive reports of typos and minor text updates to the
614 documentation. It would be great if somebody could create
615 properly-formatted patches for these corrections.
617 Technical requirements: ability to run @ref{LilyDev}.
620 LSR contains many useful examples of lilypond, but some snippets
621 are out of date and need updating. Other snippets need to be
622 advertized, and new snippets need to be sorted. We could use
623 another person to handle LSR.
625 Technical requirements: use of a web browser. LilyPond
626 requirements: you should be familiar with most of Notation
627 chapters 1 and 2 (or be willing to read the docs to find out).
629 @item Join the Frogs:
630 "Frogs" are a team of bug-fixers (because frogs eat bugs, and you
631 often find them in Ponds of Lilies) and new feature implementors.
633 Technical requirements: development environment (such as
634 @ref{LilyDev}), ability to read+write scheme and/or C++ code.
639 @node Policy decisions
640 @subsection Policy decisions
642 There are a number of policy decisions -- some of them fairly
643 important -- which we have been postponing for a few years. We
644 are now discussing them slowly and thoroughly; agenda and exact
645 proposals are online:
648 @uref{http://lilypond.org/~graham/gop/index.html}
651 Below is a list of policies which are not @qq{on the agenda} yet.
653 Note that the presence of an item on this list does @emph{not}
654 mean that everybody thinks that something needs to be done.
655 Inclusion in this simply means that one developer thinks that we
656 should discuss it. We are not going to filter this list; if any
657 developer thinks we should discuss something, just add it to the
658 bottom of the list. (the list is unsorted)
660 As GOP progresses, items from this list will be put on the agenda
661 and removed from this list. I generally try to have one month's
662 discussion planned in advance, but I may shuffle things around to
663 respond to any immediate problems in the developer community.
665 There are some item(s) not displayed here; these are questions
666 that were posed to me privately, and I do not feel justified in
667 discussing them publicly without the consent of the person(s) that
668 brought them up. They will initially be discussed privately on the
669 lilypond-hackers mailing list -- but the first question will be
670 "do we absolutely need to do this privately", and if not, the
671 discussion will take place on lilypond-devel like the other items.
673 In most policy discussions in lilypond over the past few years,
674 the first half (or more) is wasted arguing on the basis of
675 incorrect or incomplete data; once all the relevant facts are
676 brought to light, the argument is generally resolved fairly
677 quickly. In order to keep the GOP discussions focused, each topic
678 will be introduced with a collection of relevant facts and/or
679 proposals. It is, of course, impossible to predict exactly which
680 facts will be relevant to the discussion -- but spending an hour
681 or two collecting information could still save hours of
684 @warning{The estimated time required for "prep work", and the
685 following discussion, has been added to each item. At the moment,
686 there is an estimated 30 hours of prep work and 140 hours of
690 @item @strong{Patch reviewing}:
691 At the time of this writing, we have 23 (known) patches waiting
692 for review. Some from main developers; some from new developers.
693 We desperately need more people helping with lilypond, but
694 ignoring patches is the best way to drive potential contributors
695 away. This is not good.
697 (prep: 2 hours. discuss: 10 hours)
699 @item @strong{Official links to other organizations?}:
700 There's something called the "software freedom conservancy", and
701 in general, there's a bunch of "umbrella organizations". Joining
702 some of these might give us more visibility, possibly leading to
703 more users, more developers, maybe even financial grants or use in
706 (prep: 2 hours. discuss: 5 hours)
708 @item @strong{Issue tracking with google code}:
709 We use the google issue tracker, but this means that we are
710 relying on a commercial entity for a large part of our
711 development. Would it be better (safer in the long run) to use the
712 savannah bug tracker?
714 (prep: 1 hour. discuss: 5 hours)
716 @item @strong{Patch review tool}:
717 Reitveld is inconvenient in some respects: it requires a google
718 account, and there's no way to see all patches relating to
719 lilypond. Should we switch to something like gerritt?
720 @uref{http://code.google.com/p/lilypond/issues/detail?id=1184}
722 (prep: 5 hours. discuss: 15 hours)
724 @item @strong{Clarity for sponsorships}:
725 We currently do not advertize bounties and sponsorships on the
726 webpage. How much advertising do we want, and what type?
727 Should we change the "structure" / "framework" for bounties?
729 (prep: 2 hours. discuss: 10 hours)
731 @item @strong{code readability}:
732 "Our aim when producing source code for Lilypond in whatever
733 language is that it should be totally comprehensible to a
734 relatively inexperienced developer at the second reading."
737 - aids maintainability of code base
738 - "second reading" so newer developers can look up unfamiliar
740 - will help to keep things simple, even if the code is doing
741 complex stuff discourages "secret squirrel" coding, e.g. "how
742 much functionality can I squeeze into as few characters as
743 possible" "comments are for wimps"
744 - will aid not *discouraging* new developers to join the project
746 (prep: 2 hours. discuss: 10 hours)
748 @item @strong{C++ vs. scheme}:
749 what should be in scheme, what should be in C++, what can/should
750 be ported from one to the other, etc. Questions of
751 maintainability, speed (especially considering guile 2.0), and the
752 amount of current material in either form, are important.
754 (prep: 5 hours. discuss: 15 hours)
756 @item @strong{always make an issue number for patches}:
757 there is a proposal that we should always have a google code issue
758 number for every patch. This proposal is closely tied to our
759 choice of patch review tool; if we switch to a different tool (as
760 suggested in a different proposal), this proposal may become moot.
762 (prep: 1 hour. discuss: 5 hours)
764 @item @strong{initalizer lists}:
765 shoudl we use initalizer lists for C++? AFAIK they make no
766 difference for built-in types, but there's some weird case where
767 it's more efficient for objects, or something.
769 Probably not worth making this a weekly thing on its own, but we
770 can probably wrap it up with some other code-related questions.
772 (prep: 15 minutes. discuss: 3 hours)
776 @node Policy decisions (finished)
777 @subsection Policy decisions (finished)
779 Here is a record the final decisions, along with links to the
783 * GOP-PROP 1 - python formatting::
784 * GOP-PROP 2 - mentors and frogs::
785 * GOP-PROP 3 - C++ formatting::
786 * GOP-PROP 4 - lessons from 2.14::
787 * GOP-PROP 5 - build system output (not accepted)::
788 * GOP-PROP 6 - private mailing lists::
789 * GOP-PROP 7 - developers as resources::
790 * GOP-PROP 8 - issue priorities::
791 * GOP-PROP 9 - behavior of make doc::
794 @node GOP-PROP 1 - python formatting
795 @subsubsection GOP-PROP 1 - python formatting
797 We will follow the indentation described in PEP-8.
798 @uref{http://www.python.org/dev/peps/pep-0008/}
802 use 4 spaces per indentation level
805 never mix tabs and spaces (for indentation)
808 Code indented with a mixture of tabs and spaces should be
809 converted to using spaces exclusively
811 Once this is done, we should add @code{python -tt} to the build
812 system to avoid such errors in the future.
816 There should be absolutely no tab characters for indentation in
817 any @code{.py} file in lilypond git. All such files should be
818 converted to use spaces only.
820 @subsubheading Discussions
823 @uref{https://lists.gnu.org/archive/html/lilypond-devel/2011-06/msg00060.html}
824 @uref{https://lists.gnu.org/archive/html/lilypond-devel/2011-06/msg00084.html}
825 @uref{https://lists.gnu.org/archive/html/lilypond-devel/2011-06/msg00310.html}
826 @uref{https://lists.gnu.org/archive/html/lilypond-devel/2011-06/msg00574.html}
830 @node GOP-PROP 2 - mentors and frogs
831 @subsubsection GOP-PROP 2 - mentors and frogs
833 Nothing much was decided. The list of responsibilities was
834 slightly altered; see the new one in @ref{Mentors}. We should
835 encourage more use of the Frogs mailing list. There's a list of
836 contributor-mentor pairs in:
839 @uref{https://github.com/gperciva/lilypond-extra/blob/master/people/mentors.txt}
842 That's pretty much it.
844 @subsubheading Discussions
847 @uref{https://lists.gnu.org/archive/html/lilypond-devel/2011-06/msg00311.html}
853 @node GOP-PROP 3 - C++ formatting
854 @subsubsection GOP-PROP 3 - C++ formatting
856 Speaking academically, C++ code style is a "solved problem". Let's
857 pick one of the existing solutions, and let a computer deal with
858 this. Humans should not waste their time, energy, and creativity
859 manually adding tabs or spaces to source code.
861 We have modified @code{fixcc.py} to use astyle, along with extra
866 the final script will be run @strong{blindly} on the lilypond
867 source code. We will accept whatever formatting the final version
868 of this script produces, with no manual tweaking.
871 patches which have been run through this tool will not be rejected
872 for style reasons. Any code formatting @qq{desires} which are not
873 enforced by @code{fixcc.py} will not be considered grounds for
877 for now, this style will not be enforced. It is not cause for
878 concern if patches which do not follow the formatting done by
879 @code{fixcc.py} are pushed. From time to time, Graham will run
880 the formatter on the entire code base, and commit the resulting
883 In a few months, we will tighten up this policy item (with some
884 sort of automatic processing), but that is outside the scope of
885 this policy item and is a matter for later discussion.
888 after the proposal is accepted, we will leave some time for
889 existing patches to be accepted and pushed. The script was
890 run on the source code on @strong{2011 August 01}.
896 LilyPond is a GNU project, so it makes sense to follow the GNU
897 coding standards. These standards state:
900 We don’t think of these recommendations as requirements, because
901 it causes no problems for users if two different programs have
902 different formatting styles.
904 But whatever style you use, please use it consistently, since a
905 mixture of styles within one program tends to look ugly. If you
906 are contributing changes to an existing program, please follow the
907 style of that program.
910 (@uref{http://www.gnu.org/prep/standards/html_node/Formatting.html})
912 With that in mind, we do not think that we must blindly follow the
913 formatting given by the currrent version of Emacs.
915 @subheading Implementation notes
917 We can avoid some of the style change pollution in git history by
918 ignoring whitespaces changes:
924 @subsubheading Discussions
927 @uref{https://lists.gnu.org/archive/html/lilypond-devel/2011-06/msg00526.html}
928 @uref{https://lists.gnu.org/archive/html/lilypond-devel/2011-06/msg00796.html}
929 @uref{https://lists.gnu.org/archive/html/lilypond-devel/2011-07/msg00200.html}
930 @uref{https://lists.gnu.org/archive/html/lilypond-devel/2011-07/msg00525.html}
931 @uref{https://lists.gnu.org/archive/html/lilypond-devel/2011-07/msg00751.html}
932 @uref{https://lists.gnu.org/archive/html/lilypond-devel/2011-07/msg00751.html}
936 @node GOP-PROP 4 - lessons from 2.14
937 @subsubsection GOP-PROP 4 - lessons from 2.14
941 A brief history of releases:
943 @multitable @columnfractions .2 .2 .3
944 @headitem date (YYYY-MM-DD) @tab version @tab comment
945 @item 2008-10-28 @tab 2.11.63 @tab nobody checking regtests
946 @item 2008-11-17 @tab 2.11.64
947 @item 2008-11-29 @tab 2.11.65
948 @item 2008-12-23 @tab 2.12.0
949 @item 2009-01-01 @tab @tab somewhere around here, Graham becomes
950 officially release manager, but Han-Wen still builds the actual
952 @item 2009-01-01 @tab 2.12.1
953 @item 2009-01-25 @tab 2.12.2
954 @item 2009-02-28 @tab 2.13.0
955 @item 2009-06-01 @tab 2.13.1 @tab note jump in time!
956 @item 2009-06-27 @tab 2.13.2 @tab first Graham release?
957 @item 2009-07-03 @tab 2.13.3
958 @item 2009-09-09 @tab @tab Graham arrives in Glasgow, gets a
959 powerful desktop computer, and begins serious work on GUB (sending
960 bug reports to Jan). It takes approximately 100 hours until GUB
961 is stable enough to make regular releases.
962 @item 2009-09-24 @tab 2.13.4
963 @item 2009-10-02 @tab 2.13.5
964 @item 2009-10-22 @tab 2.13.6
965 @item 2009-11-05 @tab 2.13.7
967 @item 2010-01-13 @tab 2.12.3
969 @item 2010-03-19 @tab 2.13.16 @tab Bug squad starts doing a few
970 regtest comparisons, but IIRC the effort dies out after a few
973 @item 2010-08-04 @tab 2.13.29 @tab Phil starts checking regtests (BLUE)
975 @item 2011-01-12 @tab 2.13.46 @tab release candidate 1 (GREEN)
977 @item 2011-05-30 @tab 2.13.63 @tab release candidate 7 (GREEN)
978 @item 2011-06-06 @tab 2.14.0
981 @c A graphical display of bugs:
983 @c @image{bugs-2.13-visualization,png}
984 @c @image{zoom-2.13-visualization,png}
986 @subheading Carl's analysis of the bugs
988 A @file{csv} spreadsheet is available.
991 @uref{https://lists.gnu.org/archive/html/lilypond-devel/2011-06/msg00852.html}
995 @uref{lilypond-issues-analysis.csv}
996 @uref{lilypond-issues-analysis-trim-duplicates.csv}
999 There 148 issues marked with Priority=Critical in the tracker.
1001 I've done an analysis, and it looks to me like there was initially
1002 a backlog of critical issues that weren't fixed, and little work
1003 was being done to eliminate critical issues.
1005 Somewhere about 2010-08-01, critical issues started to disappear,
1006 but occasional new ones appeared.
1008 There were a couple of major changes that introduced unanticipated
1009 regressions (new spacing code, beam collision avoidance). These
1010 produced more than the expected number of regressions.
1012 It appears to me that we didn't really get serious about
1013 eliminating critical bugs until about 2010-06-15 or so. After
1014 that point, the number of critical bugs more-or-less steadily
1015 decreased until we got to a release candidate.
1017 Of particular interest, the first release candidate of 2.14 was
1018 released on 2011-01-12. Over the next 10 days, about a dozen bugs
1019 were reported and fixed. Release candidate 2 came out on
1020 2011-02-09. No surge of bugs occurred with this release.
1021 Candidate 3 came out on 2011-03-13; we got 2 bugs per week.
1022 Candidate 4 came out on 2011-03-29; 2 new bugs. Candidate 6 came
1023 out on 2011-04-07. We got a couple of bugs per week.
1025 @subheading Notes, commentary, and opinions
1028 Han-Wen: Overall, I think this cycle took too long
1033 @subsubheading Discussions
1036 @uref{https://lists.gnu.org/archive/html/lilypond-devel/2011-06/msg00797.html}
1037 @uref{https://lists.gnu.org/archive/html/lilypond-devel/2011-07/msg00364.html}
1042 @node GOP-PROP 5 - build system output (not accepted)
1043 @subsubsection GOP-PROP 5 - build system output (not accepted)
1045 This proposal was too broad; after a month of discussion, Graham
1046 withdrew the proposal. Portions of it will be introduced in later
1049 @subsubheading Discussions
1052 @uref{https://lists.gnu.org/archive/html/lilypond-devel/2011-07/msg00320.html}
1053 @uref{https://lists.gnu.org/archive/html/lilypond-devel/2011-07/msg00527.html}
1054 @uref{https://lists.gnu.org/archive/html/lilypond-devel/2011-07/msg00753.html}
1055 @uref{https://lists.gnu.org/archive/html/lilypond-devel/2011-07/msg01042.html}
1056 @uref{https://lists.gnu.org/archive/html/lilypond-devel/2011-08/msg00116.html}
1057 @uref{https://lists.gnu.org/archive/html/lilypond-devel/2011-08/msg00310.html}
1061 @node GOP-PROP 6 - private mailing lists
1062 @subsubsection GOP-PROP 6 - private mailing list
1064 Potentially sensitive or private matters will be referred to
1065 Graham. He will then decide who should discuss the matter on an
1066 ad-hoc basis, and forward or CC them on future emails.
1068 For emphasis, the project administrators are Han-Wen, Jan, and
1069 Graham; those three will always be CC'd on any important
1072 The lilypond-hackers mailing list will be removed.
1076 There is some unhappy history about this idea in our development
1080 @uref{http://lists.gnu.org/archive/html/lilypond-devel/2010-09/msg00178.html}
1081 @uref{http://web.archive.org/web/20110325004849/http://news.lilynet.net/spip.php?article121}
1082 @uref{http://lists.gnu.org/archive/html/lilypond-devel/2010-11/msg00076.html}
1085 @subheading Other projects
1087 The idea of private mailing lists is hardly uncommon in
1088 open-source software. For example,
1091 @uref{http://lwn.net/Articles/394660/} about debian-private
1092 @uref{http://subversion.apache.org/mailing-lists.html} private@@
1093 @uref{http://www.freebsd.org/administration.html#t-core}
1094 @uref{http://foundation.gnome.org/legal/} board members pledge
1095 to keep certain matters confidential
1097 every security team of every GNU/Linux distribution and OS
1100 In fact, Karl Fogel's @qq{Producing Open Source Software}
1101 explicitly suggests a private mailing list for some circumstances:
1104 [on granting commit/push access to a contributor]
1106 But here is one of the rare instances where secrecy is
1107 appropriate. You can't have votes about potential committers
1108 posted to a public mailing list, because the candidate's feelings
1109 (and reputation) could be hurt.
1111 @uref{http://producingoss.com/en/consensus-democracy.html#electorate}
1114 @subheading Board of governers, voting, etc?
1116 Many projects have an official board of directors, or a list of
1117 @qq{core developers}, with set term limits and elections and
1120 I don't think that we're that big. I think we're still small
1121 enough, and there's enough trust and consensus decisions, that we
1122 can avoid that. I would rather that we kept on going with
1123 trust+consensus for at least the next 2-3 years, and spent more
1124 time+energy on bug fixes and new features instead of
1125 administrative stuff.
1127 Project administrators are Han-Wen, Jan, and Graham.
1129 @subsubheading Discussions
1132 @uref{https://lists.gnu.org/archive/html/lilypond-devel/2011-07/msg00783.html}
1133 @uref{https://lists.gnu.org/archive/html/lilypond-devel/2011-07/msg01004.html}
1134 @uref{https://lists.gnu.org/archive/html/lilypond-devel/2011-08/msg00117.html}
1138 @node GOP-PROP 7 - developers as resources
1139 @subsubsection GOP-PROP 7 - developers as resources
1141 We shall treat developers (and contributors) as
1142 @strong{Independent volunteers}: each person does whatever they
1143 want, whenever they want. We have busy careers and lives; we make
1144 no expectations of action from anybody (with the exception of the
1145 6 people in @qq{Meister} positions).
1147 @subsubheading Discussions
1150 @uref{https://lists.gnu.org/archive/html/lilypond-devel/2011-07/msg01092.html}
1151 @uref{https://lists.gnu.org/archive/html/lilypond-devel/2011-08/msg00087.html}
1152 @uref{https://lists.gnu.org/archive/html/lilypond-devel/2011-08/msg00497.html}
1156 @node GOP-PROP 8 - issue priorities
1157 @subsubsection GOP-PROP 8 - issue priorities
1159 We will delete the @qq{priority} field of the issue tracker
1160 altogether. The @qq{type} system will be tweaked.
1167 a reproducible failure to build either @code{make} or @code{make
1168 doc}, from an empty build tree, in a first run, if
1169 @code{configure} does not report any errors.
1172 any program behaviour which is @strong{unintentionally} worse than
1173 the previous stable version or the current development version.
1174 Developers may always use the @qq{this is intentional}, or even
1175 the @qq{this is an unavoidable effect of an improvement in another
1176 area}, reason to move this to a different type.
1179 anything which stops contributors from helping out (e.g.
1180 lily-git.tcl not working, source tree(s) not being available,
1181 LilyDev being unable to compile git master, inaccurate
1182 instructions in the Contributor's Guide 2 Quick start).
1184 To limit this scope of this point, we will assume that the
1185 contributor is using the latest LilyDev and has read the relevant
1186 part(s) of the Contributor's Guide. Problems in other chapters of
1187 the CG are not sufficient to qualify as Type-Critical.
1191 @subsubheading More new/changed types and labels
1193 Unless otherwise specified, the current types and labels will
1194 continue to be used. The new types introduced by this proposal
1200 Type-crash: any segfault, regardless of what the input file looks
1201 like or which options are given. Disclaimer: this might not be
1202 possible in some cases, for example certain guile programs (we
1203 certainly can't predict if a piece of scheme will ever stop
1204 running, i.e. the halting problem), or if we rely on other
1205 programs (i.e. ghostscript). If there are any such cases that
1206 make segfault-prevention impossible, we will document those
1207 exceptions (and the issue will remain as a "crash" instead of
1208 "documentation" until the warning has been pushed).
1211 Type-maintainability: anything which makes it difficult for
1212 serious contributors to help out (e.g. difficult to find the
1213 relevant source tree(s), confusing policies, problems with
1214 automatic indentation tools, etc).
1217 Type-ugly: replaces Type-collision, and it will include things
1218 like bad slurs in addition to actual collision.
1222 A new label will be added:
1226 (label) Needs_evidence: it is not clear what the correct output
1227 should look like. We need scans, references, examples, etc.
1231 @subheading Reminding users about stars
1233 We can remind users that they can @qq{star} an issue to indicate
1234 that they care about it. Since we resolved to treat developers as
1235 independent volunteers, there is no expectation that anybody will
1236 look at those stars, but if any developer want to organize their
1237 work schedule according to the stars, they are welcome to do so.
1239 @subsubheading Discussions
1242 @uref{https://lists.gnu.org/archive/html/lilypond-devel/2011-08/msg00019.html}
1243 @uref{https://lists.gnu.org/archive/html/lilypond-devel/2011-08/msg00277.html}
1244 @uref{https://lists.gnu.org/archive/html/lilypond-devel/2011-08/msg00413.html}
1245 @uref{https://lists.gnu.org/archive/html/lilypond-devel/2011-08/msg00624.html}
1250 @node GOP-PROP 9 - behavior of make doc
1251 @subsubsection GOP-PROP 9 - behavior of make doc
1253 If there are build problems, then it should be easier to find out
1254 why it's failing. This will be achieved with log files, as well
1255 as possibly including scripts which automatically display portions
1256 of those log files for a failing build.
1258 We will also add targets for building a specific manual (for
1259 quick+easy checking of doc work), as well as for building all
1260 documentation in a specific language (either English or a
1261 translated language).
1263 When you run @code{make doc},
1268 All output will be saved to various log files, with the exception
1269 of output directly from @code{make(1)}.
1271 Note that @code{make(1)} refers to a specific executable file on
1272 unix computers, and is not a general term for the build system.
1275 By default, no other output will be displayed on the console, with
1276 one exception: if a build fails, we might display some portion(s)
1277 of log file(s) which give useful clues about the reason for the
1280 The user may optionally request additional output to be printed;
1281 this is controlled with the @code{VERBOSE=x} flag. In such cases,
1282 all output will still be written to log files; the console output
1283 is strictly additional to the log files.
1286 Logfiles from calling lilypond (as part of lilypond-book) will go in
1288 @file{$LILYPOND_BUILD_DIR/out/lybook-db/12/lily-123456.log} file. All
1289 other logfiles will go in the @file{$LILYPOND_BUILD_DIR/logfiles/}
1292 A single @code{make doc} will therefore result in hundreds of log
1293 files. Log files produced from individual lilypond runs are not
1294 under our control; apart from that, I anticipate having one or two
1295 dozen log files. As long as it is clear which log file is
1296 associated with which operation(s), I think this is entirely
1297 appropriate. The precise implementation will be discussed for
1298 specific patches as they appear.
1301 Both stderr and stdout will be saved in @code{*.log}. The order
1302 of lines from these streams should be preserved.
1305 There will be no additional @qq{progress messages} during the
1306 build process. If you run @code{make --silent}, a non-failing
1307 build should print absolutely nothing to the screen.
1310 Assuming that the loglevels patch is accepted, lilypond (inside
1311 lilypond-book) will be run with --loglevel=WARN.
1312 @uref{http://codereview.appspot.com/4822055/}
1315 Ideally, a failing build should provide hints about the reason why
1316 it failed, or at least hints about which log file(s) to examine.
1320 If this proposal is accepted, none of these policies will be
1321 assumed to apply to any other aspect of the build system.
1322 Policies for any other aspect of the build system will be
1323 discussed in separate proposals.
1325 @subheading Don't cause more build problems
1327 However, there is a danger in this approach, that vital error
1328 messages can also be lost, thus preventing the cause of the
1329 failure of a make being found. We therefore need to be
1330 exceptionally careful to move cautiously, include plenty of tests,
1331 and give time for people to experiment/find problems in each stage
1332 before proceeding to the next stage.
1334 This will be done by starting from individual lilypond calls
1335 within lilypond-book, and slowly moving to @qq{larger} targets of
1336 the build system -- after the individual lilypond calls are are
1337 producing the appropriate amount of output and this is saved in
1338 the right place and we can automatically isolate parts of a
1339 failing build, we will work on lilypond-book in general, and only
1340 then will we look at the build system itself.
1342 @subheading Implementation notes
1344 There is an existing make variable QUIET_BUILD, which
1345 alter the amount of output being displayed
1347 http://lilypond.org/doc/v2.15/Documentation/contributor/useful-make-variables}
1348 ). We are not planning on keeping this make variable.
1350 The standard way for GNU packages to give more output is with a
1351 @code{V=x} option. Presumably this is done by increasing
1352 @code{x}? If we support this option, we should still write log
1353 files; we would simply print more of the info in those log files
1356 The command @code{tee} may be useful to write to a file and
1357 display to stdout (in the case of VERBOSE).
1360 @subsubheading Discussions
1363 @uref{https://lists.gnu.org/archive/html/lilypond-devel/2011-08/msg00378.html}
1364 @uref{https://lists.gnu.org/archive/html/lilypond-devel/2011-08/msg00703.html}
1369 @n ode GOP-PROP 10 - scheme indentation
1370 @s ubsubsection GOP-PROP 10 - scheme indentation
1372 still under discussion
1374 @subsubheading Discussions
1377 @uref{https://lists.gnu.org/archive/html/lilypond-devel/2011-08/msg00625.html}
1378 @uref{https://lists.gnu.org/archive/html/lilypond-devel/2011-08/msg01026.html}
1385 @node Grand LilyPond Input Syntax Standardization (GLISS)
1386 @section Grand LilyPond Input Syntax Standardization (GLISS)
1392 Start: sortly after 2.14 comes out, which is currently estimated
1393 to happen in January 2011.
1396 Length: 6-12 months. We're not going to rush this.
1399 Goal: define an input which we commit to being
1400 machine-updateable for the forseeable future. Any future patches
1401 which change the syntax in a non-convert-ly-able format will be
1402 rejected. (subject to the limitations, below)
1403 Once this is finished, we will release lilypond 3.0.
1408 @subheading The Problem
1410 One of the biggest complaints people have with lilypond -- other
1411 than silly thing like "there's no gui" -- is the changing syntax.
1412 Now, inventing a language or standards is difficult. If you set
1413 it in stone too soon, you risk being stuck with decisions which
1414 may limit matters. If you keep on updating the syntax,
1415 interaction with older data (and other programs!) becomes complex.
1417 @subheading Scope and Limitations
1421 tweaks will not be included. Anything with \override, \set,
1422 \overrideProperty, \tweak, \revert, \unset... including even those
1423 command names themselves... is still fair game for NOT_SMART
1427 other than that, everything is on the table. Is it a problem to
1428 have the tagline inside \header? What should the default behavior
1432 we need to get standards for command names. This will help users
1433 remember them, and reduce the options for future names (and
1434 potential renamings later on). \commandOn and \commandOff seem to
1435 work well (should we *always* have an Off command?), but what
1436 about the "command" part? Should it be \nounVerbOn, or
1437 \verbNounOn ? Or \verbNotesWithExtraInformationOn ?
1440 we need standards for the location of commands. Ligature
1441 brackets, I'm looking at you. (non-postfix notation must die!)
1444 this Grand Project doesn't affect whether we have a 2.16 or not.
1445 The main problem will be deciding what to do (with a bit of
1446 messiness anticipated for \tuplet); we should definitely release a
1447 2.16 before merging _any_ of these changes.
1450 we obviously can't /guarantee/ that we'll /never/ make any
1451 non-convert-ly changes in the basic format. But we *can*
1452 guarantee that such changes would force lilypond 4.0, and that we
1453 would only do so for overwhelmingly good reasons.
1457 @subheading Workflow
1461 We're going to have lots and lots of emails flying around. The
1462 vast majority won't really fit into either -devel or -user, so
1463 we'll use a list devoted to syntax issues.
1466 Once we have a serious proposal that gained general acceptance
1467 from the separate syntax mailing list, I'll bring it to -devel.
1468 We're not going to make any changes without discussing it on
1469 -devel, but if we're going to have huge threads about English
1470 grammar and silly ideas, and I don't want to clutter up -devel.
1471 Once whatever chaotic silliness on the syntax list is settled
1472 down, I'll bring the ideas to -devel.
1475 as with GDP, I'll moderate the discussion. Not as with mailist
1476 moderation, but rather by introducing issues at specific times.
1477 We don't want a free-for-all discussion of all parts of the syntax
1478 at once; nothing will get resolved.
1481 Whenever possible, we'll decide on policies at the highest level
1482 of abstraction. For example, consider \numericTimeSignature,
1483 \slurUp, \xNotesOn, \startTextSpan, and \verylongfermata. One of
1484 them starts with the name of the notation first (slur). One has
1485 an abbreviation (x instead of cross). One has the verb at the end
1486 (On), another has it at the beginning (start). The adjective can
1487 come at the beginning (numeric, x) or end (Up). Most are in
1488 camelCase, but one isn't (verylongfermata).
1491 Instead of arguing about each individual command, we'll decide on
1492 abstract questions. Should each command begin the notation-noun,
1493 or the verb? Should all commands be in camelCase, or should we
1494 make everything other than articulations in camelCase but make
1495 articulations all lower-case? Are abbreviations allowed?
1498 Once we've answered such fundamental questions, most of the syntax
1499 should fall into place pretty easily. There might be a few odd
1500 questions left ("is it a span, or a spanner?"), but those can be
1501 settled fairly quickly.
1505 @subheading Implementation
1507 Nothing until the project is finished, then we declare the next
1508 stable release (2.16.0 or 2.18.0 ?) to be the final 2.x version,
1509 release it, then apply all the GLISS syntax changes and start
1510 testing a beta for 3.0 a week or two later.
1512 @subheading Discussion
1514 Don't respond to any of the specifics yet. Yes, we all have our
1515 pet irritations (like "what's up with \paper and \layout?!").
1516 There will be plenty of time to discuss them once GLISS starts.
1518 That said, we have a list of specific items that people really
1519 wanted to have written down. See @ref{Specific GLISS issues}.
1522 * Specific GLISS issues::
1526 @node Specific GLISS issues
1527 @subsection Specific GLISS issues
1531 add regtests for every piece of syntax (not one-command-per-file,
1532 but making a few files which, between them, use every single piece
1533 of syntax.) This is a great test for convert-ly.
1536 should GLISS cover suggested conventions? (indentation,
1537 one-bar-per-line, etc -- the kind of stuff we list for the
1538 lilypond formatting in the docs ?)
1541 how much (if any) syntactic sugar should we add? i.e.
1543 \instrumentName #'foo
1545 \set Staff.instrumentName
1547 ? Carl: maybe yes, Neil: no. (for example, it fails for
1551 the values that are used as arguments to common used overrides.
1552 Sometimes they are a symbol (e.g. #'around), sometimes a
1553 predefined variable referring to a Scheme value or object (e.g.
1554 #LEFT, #all-visible ). The main trouble is that for novice users
1555 it is not clear when there should be an apostrophe and when not.
1558 When do we need -\command and when is it just \command ?
1562 Command-line options to the lilypond binary. -dfoo counts as a
1563 tweak; we won't be trying to pin those down.
1576 If would be pedagogically simpler to realize this difference if
1577 the syntax was separate if you define a context from scratch (as
1578 is the case with \RemoveEmptyStaffContext) or if it's defined by
1579 adding onto an existing context. For example, a syntax like
1583 % Copy the current settings of the Staff context:
1585 % do whatever additional settings
1587 %%% could be used to distinguish from
1589 % Take settings from a variable:
1591 % do whatever additional settings
1597 % Start from scratch:
1606 Capitalization of identifiers: \VoiceOne ?
1611 { music expression } * 4
1613 \repeat unfold 4 { music expression }
1618 @uref{http://lists.gnu.org/archive/html/lilypond-devel/2010-04/msg00467.html}
1622 Personally, I find it easier to understand when there's a repeated
1623 8 in the half-bar position; it's much easier to see that you have
1628 %%% instead of one group of eight:
1633 trivially simple bar-lines:
1637 encourage, allow, or discourage, or disallow?
1640 indentation of \\ inside a @{@} construct.
1644 barline checks at the end of line should be preceded by at least 2
1645 spaces? barline checks should line up if possible (i.e. if you
1646 can use less than 4, 8, X empty spaces before a barline check to
1650 Why doesn't \transpose respect \relative mode?
1654 on \score vs. \new Score
1656 But in the light of a consistent syntax and semantic, I see no
1657 reason (from the users POV) to disallow it. After all, the real
1658 top-level context is a \book @{@}, isn't it, and I don't see a point
1659 in disallowing a \new Score construct just like \new Staff.
1661 From a syntactical POV, I see the following pros for \new Score:
1662 - You can write \with @{ ... @} for every other context but \Score,
1663 which (for consistency) should also work with \new Score.
1664 - When there's a \new Foo Bar, there's also a \context Foo Bar,
1665 which makes the same as a parallel instantiation of all Bar's.
1666 - [Quoting Rune from
1667 @uref{http://www.mail-archive.com/lilypond-devel@@gnu.org/msg14713.html}
1668 "I know that the \score-statement is a syntactical construct,
1669 but I think it would be nice to hide this fact from the users. I
1670 think we could make the use of score-block much more intuitive if
1671 changing the syntax to \new \Score and adding an implicit
1672 sequential-statement to the score."
1677 @uref{http://code.google.com/p/lilypond/issues/detail?id=1322}
1678 about \new vs. \context.
1682 Let users add their own items to the parser? comment 11 on:
1683 @uref{http://code.google.com/p/lilypond/issues/detail?id=1322}
1686 should engravers be pluralized (note_heads_engraver) or not
1687 (note_head_engraver) ?
1690 should we allow numbers in identifier names? Issue:
1691 @uref{http://code.google.com/p/lilypond/issues/detail?id=1670}
1694 should we officially allow accented characters? in general, how
1695 do we feel about utf-8 stuff?
1698 for the sake of completeness/simplicity, what about *disallowing*
1699 the "one-note" form of a music expression? i.e. only allowing
1702 \transpose c d { e1 }
1703 \transpose c d << e1 >>
1712 What should be the officially encouraged way of writing music for
1713 transposing instruments? Maybe it should be simplified?
1714 See http://lists.gnu.org/archive/html/lilypond-user/2011-07/msg00130.html
1719 @node Unsorted policies
1720 @section Unsorted policies
1722 @subsubheading Language-specific mailing lists
1724 A translator can ask for an official lilypond-xy mailing list once
1725 they've finished all @qq{priority 1} translation items.
1727 @subsubheading Performing yearly copyright update (@qq{grand-replace})
1729 At the start of each year, copyright notices for all source files
1730 should be refreshed by running the following command from the top of
1737 Internally, this invokes the script @file{scripts/build/grand-replace.py},
1738 which performs a regular expression substitution for old-year -> new-year
1739 wherever it finds a valid copyright notice.
1741 Note that snapshots of third party files such as @file{texinfo.tex} should
1742 not be included in the automatic update; @file{grand-replace.py} ignores these
1743 files if they are listed in the variable @code{copied_files}.
1746 @subsubheading Push git access
1748 Git access is given out when a contributor has a significant
1749 record of patches being accepted without problems. If existing
1750 developers are tired of pushing patches for a contributor, we'll
1751 discuss giving them push access. Unsolicited requests from
1752 contributors for access will almost always be turned down.