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 primary jobs to help organize all our contributors:
113 @unnumberedsubsec The Bug Meister
115 The Bug Meister's responsibilities are:
120 To organize the individual Bug Squad volunteers, making sure that
121 each member is aware of their responsibilities. See
125 To train new Bug Squad volunteers in the Issue Tracker process. See
129 To have the final say on our policies for Issues and their
130 classification. See @ref{Issue classification}.
134 Current Bug Meister: Colin Hall @email{bug-lilypond@@gnu.org}
137 @unnumberedsubsec The Doc Meister
139 The Doc Meister's responsibilities are:
144 To train new volunteers in our Documentation style and policy,
145 including organizing LilyPond Snippet Repository (LSR) work.
148 To organize the individual volunteers -- who does what on which job --
149 and to check that everything is running smoothly.
152 To have final say on any Documentation policy. See
153 @ref{Documentation policy}.
157 Current Doc Meister: None
160 @unnumberedsubsec The Patch Meister
162 The Patch Meister's responsibilities are:
167 To keep track of all patches submitted for testing and review. This
168 includes scanning the bug and dev email lists looking for any patches
169 submitted by @q{random} contributors and advising them on how to submit
170 a patch for testing and review. See @ref{Uploading a patch for review}
171 and @ref{The patch review cycle}.
174 To makes sure that any patch submitted has a corresponding Issue Tracker
175 and Rietveld Issue created for it before it enters the testing and
176 review process. See @ref{Issues}.
179 Updates all Issue statuses for all patches that are currently in the
180 testing and review process periodically -- currently every 3 - 4 days.
181 See @ref{Patch handling}.
185 @warning{The Patch Meister's role is a purely administrative one and no
186 programming skill or judgement is assumed or required.}
188 Currently: James Lowe @email{pkx@@gnu.org}
191 @unnumberedsubsec The Translation Meister
193 The Translation Meister's responsibilities are:
198 To train new documentation translators in the translation process. See
199 @ref{Translating the documentation}.
202 To update the translation priority list and handle the merging of the
203 translation branches (in both directions).
206 To have final say on any Translation management policies. See
207 @ref{Translating the documentation}.
211 Currently: Francisco Vila @email{translations@@lilynet.net}
215 @node Managing Staging and Master branches with Patchy
216 @section Managing Staging and Master branches with Patchy
219 The script 'test-patches.py' no longer works with code.google.com since
220 Google changed their authentication method.
224 * Overview of Patchy::
225 * Patchy requirements::
226 * Installing Patchy::
227 * Configuring Patchy::
228 * Running the script::
229 * Automating Patchy::
230 * Troubleshooting Patchy::
233 @node Overview of Patchy
234 @subsection Overview of Patchy
236 No programmatic skill is required to run Patchy; although knowledge of
237 compiling LilyPond and its documentation along with understanding how to
238 configure the @var{PATH} environment of your computer is required. See
239 @ref{Working with source code}.
241 The script @code{lilypond-patchy-staging.py} checks for any new commits
242 in @code{remote/origin/staging}, makes sure that the new HEAD compiles
243 along with all the LilyPond documentation. Then finally pushing to
244 @code{remote/origin/master}. This script can be run and left
245 unattended, requiring no human intervention.
247 Patchy can also be configured to send emails after each successful (or
248 unsuccessful) operation. This is not a requirement and is turned off
251 @c Need to explain in more detail how to set up Patchy for email but
252 @c as I don't use myself it I have no experience - JL
255 @node Patchy requirements
256 @subsection Patchy requirements
261 A full local copy of the source code. See
262 @ref{Working with source code}.
265 All the software needed for compiling LilyPond @emph{and} the
266 documentation. Unlike testing patches, being able to build the full set
267 of LilyPond's documentation is required to be able to test & push new
268 commits. See @ref{Compiling}.
271 Commit access @emph{is} required to test and push new commits, but a
272 valid login to @uref{http://code.google.com/} is @emph{not}. See
278 @node Installing Patchy
279 @subsection Installing Patchy
281 The Patchy scripts are not part of the LilyPond code base, but can be
282 downloaded from @uref{https://github.com/gperciva/lilypond-extra/}. The
283 scripts and related Python libraries are all located in the
284 @file{patches/} directory.
286 Alternatively, use @code{git clone};
289 git clone https://github.com/gperciva/lilypond-extra/
292 This makes it simpler to update the scripts if any changes are ever made
293 to them. Finally, add the location of the @file{patches/} directory to
297 @node Configuring Patchy
298 @subsection Configuring Patchy
300 @warning{It is recommended to create a new user on your computer
301 specifically to run the Patchy scripts as a security precaution and that
302 this user should not have any administrative privileges. Also do not
303 set password protection for your ssh key else you will not be able to
304 run the scripts unattended.}
309 Make sure the environment variables @var{LILYPOND_GIT} and
310 @var{LILYPOND_BUILD_DIR} are configured appropriately. See
311 @ref{Environment variables}.
314 Manually run either the @code{lilypond-patchy-staging.py} script and
318 Warning: using default config; please edit /home/joe/.lilypond-patchy-config
319 Are you sure that you want to continue with the default config? (y/[n])
322 Answer @qq{@code{n}} and press enter.
324 The next time either of the scripts are run they will use the
325 @code{.lilypond-patchy-config} settings copied to your @code{$HOME}
329 Manually edit the @file{.lilypond-patchy-config} file, located in your
330 @code{$HOME} directory to change any of the default settings.
339 All @code{make} operations are run with;
341 extra_make_options = -j3 CPU_COUNT=3
344 See @ref{Saving time with the -j option}
347 A complete build of all the LilyPond documentation is @emph{not}
350 patch_test_build_docs = no
354 Each instance of either a patch test or commit test & push is logged in;
356 auto_compile_results_dir = ~/lilypond-auto-compile-results/
360 Both scripts will perform their build operations in;
362 build_dir = /tmp/lilypond-autobuild/
367 The script creates a clones of @code{staging} and @code{master}
368 branches (prefixed with @code{test-}) with a third branch, called
369 @code{test-master-lock} used as a check to protect against two or more
370 instances of Patchy being run locally at the same time.
373 @node Running the script
374 @subsection Running the script
376 @code{lilypond-patchy-staging.py} is run @emph{without} any arguments.
377 It then checks to see if @code{remote/origin/staging} is
378 @qq{further ahead} than @code{remote/origin/master}.
381 If there are no new differences between the two branches since the last
382 run check, the script will report something like this:
385 (UTC) Begin LilyPond compile, previous commit at 4726764cb591f622e7893407db0e7d42bcde90d9
386 Success: No new commits in staging
390 If there are any differences between the two branches since the last
391 run check, (or if the script cannot for any reason, locate the last
392 instance of a commit that it checked) it will report something like
396 (UTC) Begin LilyPond compile, previous commit at 4726764cb591f622e7893407db0e7d42bcde90d9
397 Merged staging, now at: 79e98a773b6570cfa28a15775a9dea3d3e54d6b5
398 Success: ./autogen.sh --noconfigure
399 Success: /tmp/lilypond-autobuild/configure --disable-optimising
403 and proceed with running @code{make}, @code{make test} and a
404 @code{make doc}. Unlike @code{test-patches.py} if all the tests pass,
405 the script then pushes the changes to @code{remote/origin/master}.
409 Success: nice make clean
410 Success: nice make -j7 CPU_COUNT=7
411 Success: nice make test -j7 CPU_COUNT=7
412 Success: nice make doc -j7 CPU_COUNT=7
413 To ssh://joe@@git.sv.gnu.org/srv/git/lilypond.git
414 79e98a7..4726764 test-staging -> master
415 Success: pushed to master
418 @warning{In the case where any of the @code{lilypond-patchy-staging.py}
419 tests fail, do not try to push your own fixes but report the failures to
420 the Developers List <lilypond-devel@@gnu.org> for advice.}
423 @node Automating Patchy
424 @subsection Automating Patchy
426 To run as a cron job make sure you have;
430 notify_non_action = no
433 in @file{$HOME/.lilypond-patchy-config} to avoid any unintentional email
436 Assuming that Patchy run a user @qq{patchy}, create a file called
437 @file{$HOME/lilypond-patchy.cron}, adapting it as necessary (the
438 @code{/2} means @qq{run this every 2 hours}):
441 02 0-23/2 * * * /home/patchy/lilypond-extra/patches/lilypond-patchy-staging.py
444 @warning{@code{cron} will not inherit environment variables so you must
445 re-define any variables inside @file{$HOME/lilypond-patchy.cron}. For
446 instance, @var{LILYPOND_GIT} may need to be defined if
447 @var{git_repository_dir} is not correctly set in
448 @file{$HOME/.lilypond-patchy-config}.}
450 Finally, apply the cron job (you may need superuser privileges for
454 crontab -u patchy /home/patchy/lilypond-patchy.cron
458 @node Troubleshooting Patchy
459 @subsection Troubleshooting Patchy
461 The following is a list of the most common messages that the scripts
462 may report with explanations.
465 this Git revision has already been pushed by an operator other than this Patchy.
471 Another, remote, machine has already tested and pushed the new commits
475 You may also see this if the auto-build files have been deleted and this
476 computer has previously already pushed the listed commit ID to
482 test-master-lock and PID entry exist but previous Patchy
483 run (PID xxxxx) died, resetting test-master-lock anyway.
487 A previous attempt was unsuccessful for some reason and the scripts were
488 not able to tidy up after themselves (for example if you manually halt
489 the process by killing it or closing the terminal you may have been
490 running the script in). The @code{test-master-lock} branch was
491 therefore not able to be deleted cleanly however, nothing needs to be
492 done the scripts will rebuild any tests it needs to.
495 fatal: A branch named 'test-master-lock' already exists.
501 There is another instance of Patchy running on your computer that is
502 testing the same tracker issue.
505 A previous test attempt was unsuccessful for some reason and the scripts
506 were not able to tidy up after themselves (for example if you manually
507 halt the testing process by killing it or closing the terminal you may
508 have been running the script in). The @code{test-master-lock} branch
509 was therefore not able to be deleted cleanly, in this case you must
510 manually delete the @code{test-master-lock} branch in your
511 @code{$LILYPOND_GIT} directory.
514 git branch -d test-master-lock
518 It may be wise to also manually delete @code{test-master} and
519 @code{test-staging} too, just to be safe.
526 Another instance (PID xxxxx) is already running.
530 This occurs when trying to run @code{lilypond-patchy-staging.py} when
531 another instance of either script is already running locally.
536 @node Administrative mailing list
537 @section Administrative mailing list
539 A mailing list for administrative issues is maintained at
540 @code{lilypond-hackers@@gnu.org}.
542 This list is intended to be used for discussions that should be kept
543 private. Therefore, the archives are closed to the public.
545 Subscription to this list is limited to certain senior developers.
547 At the present time, the list is dormant.
549 Details about the criteria for membership, the types of discussion
550 to take place on the list, and other policies for the hackers list
551 will be finalized during the
552 @ref{Grand Organization Project (GOP)}.
556 @node Grand Organization Project (GOP)
557 @section Grand Organization Project (GOP)
563 Clarify the various development tasks by writing down the policies
564 and techniques and/or simplifying the tasks directly.
567 Get more people involved in development: specifically, find people
568 to do easy tasks to allow advanced developers to concentrate on
577 * Policy decisions (finished)::
581 @subsection Motivation
583 Most readers are probably familiar with the LilyPond Grand
584 Documentation Project, which ran from Aug 2007 to Aug 2008. This
585 project involved over 20 people and resulted in an almost complete
586 rewrite of the documentation. Most of those contributors were
587 normal users who decided to volunteer their time and effort to
588 improve lilypond for everybody. By any measure, it was a great
591 The Grand Organization Project aims to do the same thing with a
592 larger scope -- instead of focusing purely on documentation, the
593 project aims to improve all parts of LilyPond and its community.
594 Just as with GDP, the main goal is to encourage and train users to
595 become more involved.
597 If you have never contributed to an open-source project before --
598 especially if you use Windows or OSX and do not know how to
599 program or compile programs -- you may be wondering if there's
600 anything you can do. Rest assured that you @emph{can} help.
602 @subheading "Trickle-up" development
604 One of the reasons I'm organizing GOP is "trickle-up"
605 development. The idea is this: doing easy tasks frees up advanced
606 developers to do harder tasks. Don't ask "am I the @emph{best}
607 person for this job"; instead, ask "am I @emph{capable} of doing
608 this job, so that the current person can do stuff I @emph{can't}
611 For example, consider lilypond's poor handling of grace notes in
612 conjunction with clef and tempo changes. Fixing this will require
613 a fair amount of code rewriting, and would take an advanced
614 developer a few weeks to do. It's clearly beyond the scope of a
615 normal user, so we might as well sit back and do nothing, right?
617 No; we @emph{can} help, indirectly. Suppose that our normal user
618 starts answering more emails on lilypond-user. This in turn means
619 that documentation writers don't need to answer those emails, so
620 they can spend more time improving the docs. I've noticed that all
621 doc writers tackle harder and harder subjects, and when they start
622 writing docs on scheme programming and advanced tweaks, they start
623 contributing bug fixes to lilypond. Having people performing these
624 easy-to-moderate bug fixes frees up the advanced developers to
625 work on the really hard stuff... like rewriting the grace note
628 Having 1 more normal user answering emails on lilypond-user won't
629 have a dramatic @q{trickle-up} effect all by itself, of course. But if
630 we had 8 users volunteering to answer emails, 6 users starting to
631 write documentation, and 2 users editing LSR... well, that would
632 free up a lot of current bug-fixing-capable contributors to focus
633 on that, and we could start to make a real dent in the number of
634 bugs in lilypond. Quite apart from the eased workload, having that
635 many new helpers will provide a great moral boost!
638 @subsection Ongoing jobs
640 Although GOP is a short-term project, the main goal is to train
641 more people to handle ongoing jobs. The more people doing these
642 jobs, the lighter the work will be, and the more we can get done
645 Also, it would be nice if we had at least one "replacement" /
646 "understudy" for each role -- too many tasks are only being done
647 by one person, so if that person goes on vacation or gets very
648 busy with other matters, work in that area grinds to a halt.
650 @subheading Jobs for normal users
654 LilyPond is sometimes critized for not listening to users, but
655 whenever we ask for opinions about specific issues, we never get
656 enough feedback. This is somewhat aggravating.
657 We need a group of users to make a dedicated effort to test and
658 give feedback. If there's new documentation, read it. If there's
659 an experimental binary, download it and try compiling a score with
660 it. If we're trying to name a new command, think about it and give
663 @item lilypond-user support:
664 I think it would be nice if we had an official team of users
667 @item LilyPond Report:
668 Keeping a monthly newsletter running is a non-trivial task. A lot
669 of work is needed to organize it; it would be great if we could
670 split up the work. One person could write the Snippet of the
671 Month, another person could do Quotes of the Month, another person
672 could do interviews, etc.
675 Although GDP (the Grand Documentation Project) did great work,
676 there's still many tasks remaining.
679 Keeping the documentation translations is a monumental task; we
680 need all the help we can get!
684 @subheading Jobs for advanced users for developers
687 @item Git help for writers:
688 We often receive reports of typos and minor text updates to the
689 documentation. It would be great if somebody could create
690 properly-formatted patches for these corrections.
692 Technical requirements: ability to run @ref{LilyDev}.
695 LSR contains many useful examples of lilypond, but some snippets
696 are out of date and need updating. Other snippets need to be
697 advertized, and new snippets need to be sorted. We could use
698 another person to handle LSR.
700 Technical requirements: use of a web browser. LilyPond
701 requirements: you should be familiar with most of Notation
702 chapters 1 and 2 (or be willing to read the docs to find out).
704 @item Join the Frogs:
705 "Frogs" are a team of bug-fixers (because frogs eat bugs, and you
706 often find them in Ponds of Lilies) and new feature implementors.
708 Technical requirements: development environment (such as
709 @ref{LilyDev}), ability to read+write scheme and/or C++ code.
714 @node Policy decisions
715 @subsection Policy decisions
717 There are a number of policy decisions -- some of them fairly
718 important -- which we have been postponing for a few years. We
719 are now discussing them slowly and thoroughly; agenda and exact
720 proposals are online:
723 @uref{http://lilypond.org/~graham/gop/index.html}
726 Below is a list of policies which are not @qq{on the agenda} yet.
728 Note that the presence of an item on this list does @emph{not}
729 mean that everybody thinks that something needs to be done.
730 Inclusion in this simply means that one developer thinks that we
731 should discuss it. We are not going to filter this list; if any
732 developer thinks we should discuss something, just add it to the
733 bottom of the list. (the list is unsorted)
735 As GOP progresses, items from this list will be put on the agenda
736 and removed from this list. I generally try to have one month's
737 discussion planned in advance, but I may shuffle things around to
738 respond to any immediate problems in the developer community.
740 There are some item(s) not displayed here; these are questions
741 that were posed to me privately, and I do not feel justified in
742 discussing them publicly without the consent of the person(s) that
743 brought them up. They will initially be discussed privately on the
744 lilypond-hackers mailing list -- but the first question will be
745 "do we absolutely need to do this privately", and if not, the
746 discussion will take place on lilypond-devel like the other items.
748 In most policy discussions in lilypond over the past few years,
749 the first half (or more) is wasted arguing on the basis of
750 incorrect or incomplete data; once all the relevant facts are
751 brought to light, the argument is generally resolved fairly
752 quickly. In order to keep the GOP discussions focused, each topic
753 will be introduced with a collection of relevant facts and/or
754 proposals. It is, of course, impossible to predict exactly which
755 facts will be relevant to the discussion -- but spending an hour
756 or two collecting information could still save hours of
759 @warning{The estimated time required for "prep work", and the
760 following discussion, has been added to each item. At the moment,
761 there is an estimated 30 hours of prep work and 140 hours of
765 @item @strong{Patch reviewing}:
766 At the time of this writing, we have 23 (known) patches waiting
767 for review. Some from main developers; some from new developers.
768 We desperately need more people helping with lilypond, but
769 ignoring patches is the best way to drive potential contributors
770 away. This is not good.
772 (prep: 2 hours. discuss: 10 hours)
774 @item @strong{Official links to other organizations?}:
775 There's something called the "software freedom conservancy", and
776 in general, there's a bunch of "umbrella organizations". Joining
777 some of these might give us more visibility, possibly leading to
778 more users, more developers, maybe even financial grants or use in
781 (prep: 2 hours. discuss: 5 hours)
783 @item @strong{Issue tracking with google code}:
784 We use the google issue tracker, but this means that we are
785 relying on a commercial entity for a large part of our
786 development. Would it be better (safer in the long run) to use the
787 savannah bug tracker?
789 (prep: 1 hour. discuss: 5 hours)
791 @item @strong{Patch review tool}:
792 Reitveld is inconvenient in some respects: it requires a google
793 account, and there's no way to see all patches relating to
794 lilypond. Should we switch to something like gerritt?
795 @uref{http://code.google.com/p/lilypond/issues/detail?id=1184}
797 (prep: 5 hours. discuss: 15 hours)
799 @item @strong{Clarity for sponsorships}:
800 We currently do not advertize bounties and sponsorships on the
801 webpage. How much advertising do we want, and what type?
802 Should we change the "structure" / "framework" for bounties?
804 (prep: 2 hours. discuss: 10 hours)
806 @item @strong{code readability}:
807 "Our aim when producing source code for LilyPond in whatever
808 language is that it should be totally comprehensible to a
809 relatively inexperienced developer at the second reading."
812 - aids maintainability of code base
813 - "second reading" so newer developers can look up unfamiliar
815 - will help to keep things simple, even if the code is doing
816 complex stuff discourages "secret squirrel" coding, e.g. "how
817 much functionality can I squeeze into as few characters as
818 possible" "comments are for wimps"
819 - will aid not *discouraging* new developers to join the project
821 (prep: 2 hours. discuss: 10 hours)
823 @item @strong{C++ vs. scheme}:
824 what should be in scheme, what should be in C++, what can/should
825 be ported from one to the other, etc. Questions of
826 maintainability, speed (especially considering guile 2.0), and the
827 amount of current material in either form, are important.
829 (prep: 5 hours. discuss: 15 hours)
831 @item @strong{always make an issue number for patches}:
832 there is a proposal that we should always have a google code issue
833 number for every patch. This proposal is closely tied to our
834 choice of patch review tool; if we switch to a different tool (as
835 suggested in a different proposal), this proposal may become moot.
837 (prep: 1 hour. discuss: 5 hours)
839 @item @strong{initalizer lists}:
840 shoudl we use initalizer lists for C++? AFAIK they make no
841 difference for built-in types, but there's some weird case where
842 it's more efficient for objects, or something.
844 Probably not worth making this a weekly thing on its own, but we
845 can probably wrap it up with some other code-related questions.
847 (prep: 15 minutes. discuss: 3 hours)
851 @node Policy decisions (finished)
852 @subsection Policy decisions (finished)
854 Here is a record the final decisions, along with links to the
858 * GOP-PROP 1 - python formatting::
859 * GOP-PROP 2 - mentors and frogs::
860 * GOP-PROP 3 - C++ formatting::
861 * GOP-PROP 4 - lessons from 2.14::
862 * GOP-PROP 5 - build system output (not accepted)::
863 * GOP-PROP 6 - private mailing lists::
864 * GOP-PROP 7 - developers as resources::
865 * GOP-PROP 8 - issue priorities::
866 * GOP-PROP 9 - behavior of make doc::
869 @node GOP-PROP 1 - python formatting
870 @subsubsection GOP-PROP 1 - python formatting
872 We will follow the indentation described in PEP-8.
873 @uref{http://www.python.org/dev/peps/pep-0008/}
877 use 4 spaces per indentation level
880 never mix tabs and spaces (for indentation)
883 Code indented with a mixture of tabs and spaces should be
884 converted to using spaces exclusively
886 Once this is done, we should add @code{python -tt} to the build
887 system to avoid such errors in the future.
891 There should be absolutely no tab characters for indentation in
892 any @code{.py} file in lilypond git. All such files should be
893 converted to use spaces only.
895 @subsubheading Discussions
898 @uref{https://lists.gnu.org/archive/html/lilypond-devel/2011-06/msg00060.html}
899 @uref{https://lists.gnu.org/archive/html/lilypond-devel/2011-06/msg00084.html}
900 @uref{https://lists.gnu.org/archive/html/lilypond-devel/2011-06/msg00310.html}
901 @uref{https://lists.gnu.org/archive/html/lilypond-devel/2011-06/msg00574.html}
905 @node GOP-PROP 2 - mentors and frogs
906 @subsubsection GOP-PROP 2 - mentors and frogs
908 Nothing much was decided. The list of responsibilities was
909 slightly altered; see the new one in @ref{Mentors}. We should
910 encourage more use of the Frogs mailing list. There's a list of
911 contributor-mentor pairs in:
914 @uref{https://github.com/gperciva/lilypond-extra/blob/master/people/mentors.txt}
917 That's pretty much it.
919 @subsubheading Discussions
922 @uref{https://lists.gnu.org/archive/html/lilypond-devel/2011-06/msg00311.html}
928 @node GOP-PROP 3 - C++ formatting
929 @subsubsection GOP-PROP 3 - C++ formatting
931 Speaking academically, C++ code style is a "solved problem". Let's
932 pick one of the existing solutions, and let a computer deal with
933 this. Humans should not waste their time, energy, and creativity
934 manually adding tabs or spaces to source code.
936 We have modified @code{fixcc.py} to use astyle, along with extra
941 the final script will be run @strong{blindly} on the lilypond
942 source code. We will accept whatever formatting the final version
943 of this script produces, with no manual tweaking.
946 patches which have been run through this tool will not be rejected
947 for style reasons. Any code formatting @qq{desires} which are not
948 enforced by @code{fixcc.py} will not be considered grounds for
952 for now, this style will not be enforced. It is not cause for
953 concern if patches which do not follow the formatting done by
954 @code{fixcc.py} are pushed. From time to time, Graham will run
955 the formatter on the entire code base, and commit the resulting
958 In a few months, we will tighten up this policy item (with some
959 sort of automatic processing), but that is outside the scope of
960 this policy item and is a matter for later discussion.
963 after the proposal is accepted, we will leave some time for
964 existing patches to be accepted and pushed. The script was
965 run on the source code on @strong{2011 August 01}.
971 LilyPond is a GNU project, so it makes sense to follow the GNU
972 coding standards. These standards state:
975 We don’t think of these recommendations as requirements, because
976 it causes no problems for users if two different programs have
977 different formatting styles.
979 But whatever style you use, please use it consistently, since a
980 mixture of styles within one program tends to look ugly. If you
981 are contributing changes to an existing program, please follow the
982 style of that program.
985 (@uref{http://www.gnu.org/prep/standards/html_node/Formatting.html})
987 With that in mind, we do not think that we must blindly follow the
988 formatting given by the currrent version of Emacs.
990 @subheading Implementation notes
992 We can avoid some of the style change pollution in git history by
993 ignoring whitespaces changes:
999 @subsubheading Discussions
1002 @uref{https://lists.gnu.org/archive/html/lilypond-devel/2011-06/msg00526.html}
1003 @uref{https://lists.gnu.org/archive/html/lilypond-devel/2011-06/msg00796.html}
1004 @uref{https://lists.gnu.org/archive/html/lilypond-devel/2011-07/msg00200.html}
1005 @uref{https://lists.gnu.org/archive/html/lilypond-devel/2011-07/msg00525.html}
1006 @uref{https://lists.gnu.org/archive/html/lilypond-devel/2011-07/msg00751.html}
1007 @uref{https://lists.gnu.org/archive/html/lilypond-devel/2011-07/msg00751.html}
1011 @node GOP-PROP 4 - lessons from 2.14
1012 @subsubsection GOP-PROP 4 - lessons from 2.14
1016 A brief history of releases:
1018 @multitable @columnfractions .2 .2 .3
1019 @headitem date (YYYY-MM-DD) @tab version @tab comment
1020 @item 2008-10-28 @tab 2.11.63 @tab nobody checking regtests
1021 @item 2008-11-17 @tab 2.11.64
1022 @item 2008-11-29 @tab 2.11.65
1023 @item 2008-12-23 @tab 2.12.0
1024 @item 2009-01-01 @tab @tab somewhere around here, Graham becomes
1025 officially release manager, but Han-Wen still builds the actual
1027 @item 2009-01-01 @tab 2.12.1
1028 @item 2009-01-25 @tab 2.12.2
1029 @item 2009-02-28 @tab 2.13.0
1030 @item 2009-06-01 @tab 2.13.1 @tab note jump in time!
1031 @item 2009-06-27 @tab 2.13.2 @tab first Graham release?
1032 @item 2009-07-03 @tab 2.13.3
1033 @item 2009-09-09 @tab @tab Graham arrives in Glasgow, gets a
1034 powerful desktop computer, and begins serious work on GUB (sending
1035 bug reports to Jan). It takes approximately 100 hours until GUB
1036 is stable enough to make regular releases.
1037 @item 2009-09-24 @tab 2.13.4
1038 @item 2009-10-02 @tab 2.13.5
1039 @item 2009-10-22 @tab 2.13.6
1040 @item 2009-11-05 @tab 2.13.7
1042 @item 2010-01-13 @tab 2.12.3
1044 @item 2010-03-19 @tab 2.13.16 @tab Bug squad starts doing a few
1045 regtest comparisons, but IIRC the effort dies out after a few
1048 @item 2010-08-04 @tab 2.13.29 @tab Phil starts checking regtests (BLUE)
1050 @item 2011-01-12 @tab 2.13.46 @tab release candidate 1 (GREEN)
1052 @item 2011-05-30 @tab 2.13.63 @tab release candidate 7 (GREEN)
1053 @item 2011-06-06 @tab 2.14.0
1056 @c A graphical display of bugs:
1058 @c @image{bugs-2.13-visualization,png}
1059 @c @image{zoom-2.13-visualization,png}
1061 @subheading Carl's analysis of the bugs
1063 A @file{csv} spreadsheet is available.
1066 @uref{https://lists.gnu.org/archive/html/lilypond-devel/2011-06/msg00852.html}
1070 @uref{lilypond-issues-analysis.csv}
1071 @uref{lilypond-issues-analysis-trim-duplicates.csv}
1074 There 148 issues marked with Priority=Critical in the tracker.
1076 I've done an analysis, and it looks to me like there was initially
1077 a backlog of critical issues that weren't fixed, and little work
1078 was being done to eliminate critical issues.
1080 Somewhere about 2010-08-01, critical issues started to disappear,
1081 but occasional new ones appeared.
1083 There were a couple of major changes that introduced unanticipated
1084 regressions (new spacing code, beam collision avoidance). These
1085 produced more than the expected number of regressions.
1087 It appears to me that we didn't really get serious about
1088 eliminating critical bugs until about 2010-06-15 or so. After
1089 that point, the number of critical bugs more-or-less steadily
1090 decreased until we got to a release candidate.
1092 Of particular interest, the first release candidate of 2.14 was
1093 released on 2011-01-12. Over the next 10 days, about a dozen bugs
1094 were reported and fixed. Release candidate 2 came out on
1095 2011-02-09. No surge of bugs occurred with this release.
1096 Candidate 3 came out on 2011-03-13; we got 2 bugs per week.
1097 Candidate 4 came out on 2011-03-29; 2 new bugs. Candidate 6 came
1098 out on 2011-04-07. We got a couple of bugs per week.
1100 @subheading Notes, commentary, and opinions
1103 Han-Wen: Overall, I think this cycle took too long
1108 @subsubheading Discussions
1111 @uref{https://lists.gnu.org/archive/html/lilypond-devel/2011-06/msg00797.html}
1112 @uref{https://lists.gnu.org/archive/html/lilypond-devel/2011-07/msg00364.html}
1117 @node GOP-PROP 5 - build system output (not accepted)
1118 @subsubsection GOP-PROP 5 - build system output (not accepted)
1120 This proposal was too broad; after a month of discussion, Graham
1121 withdrew the proposal. Portions of it will be introduced in later
1124 @subsubheading Discussions
1127 @uref{https://lists.gnu.org/archive/html/lilypond-devel/2011-07/msg00320.html}
1128 @uref{https://lists.gnu.org/archive/html/lilypond-devel/2011-07/msg00527.html}
1129 @uref{https://lists.gnu.org/archive/html/lilypond-devel/2011-07/msg00753.html}
1130 @uref{https://lists.gnu.org/archive/html/lilypond-devel/2011-07/msg01042.html}
1131 @uref{https://lists.gnu.org/archive/html/lilypond-devel/2011-08/msg00116.html}
1132 @uref{https://lists.gnu.org/archive/html/lilypond-devel/2011-08/msg00310.html}
1136 @node GOP-PROP 6 - private mailing lists
1137 @subsubsection GOP-PROP 6 - private mailing list
1139 Potentially sensitive or private matters will be referred to
1140 Graham. He will then decide who should discuss the matter on an
1141 ad-hoc basis, and forward or CC them on future emails.
1143 For emphasis, the project administrators are Han-Wen, Jan, and
1144 Graham; those three will always be CC'd on any important
1147 The lilypond-hackers mailing list will be removed.
1151 There is some unhappy history about this idea in our development
1155 @uref{http://lists.gnu.org/archive/html/lilypond-devel/2010-09/msg00178.html}
1156 @uref{http://web.archive.org/web/20110325004849/http://news.lilynet.net/spip.php?article121}
1157 @uref{http://lists.gnu.org/archive/html/lilypond-devel/2010-11/msg00076.html}
1160 @subheading Other projects
1162 The idea of private mailing lists is hardly uncommon in
1163 open-source software. For example,
1166 @uref{http://lwn.net/Articles/394660/} about debian-private
1167 @uref{http://subversion.apache.org/mailing-lists.html} private@@
1168 @uref{http://www.freebsd.org/administration.html#t-core}
1169 @uref{http://foundation.gnome.org/legal/} board members pledge
1170 to keep certain matters confidential
1172 every security team of every GNU/Linux distribution and OS
1175 In fact, Karl Fogel's @qq{Producing Open Source Software}
1176 explicitly suggests a private mailing list for some circumstances:
1179 [on granting commit/push access to a contributor]
1181 But here is one of the rare instances where secrecy is
1182 appropriate. You can't have votes about potential committers
1183 posted to a public mailing list, because the candidate's feelings
1184 (and reputation) could be hurt.
1186 @uref{http://producingoss.com/en/consensus-democracy.html#electorate}
1189 @subheading Board of governers, voting, etc?
1191 Many projects have an official board of directors, or a list of
1192 @qq{core developers}, with set term limits and elections and
1195 I don't think that we're that big. I think we're still small
1196 enough, and there's enough trust and consensus decisions, that we
1197 can avoid that. I would rather that we kept on going with
1198 trust+consensus for at least the next 2-3 years, and spent more
1199 time+energy on bug fixes and new features instead of
1200 administrative stuff.
1202 Project administrators are Han-Wen, Jan, and Graham.
1204 @subsubheading Discussions
1207 @uref{https://lists.gnu.org/archive/html/lilypond-devel/2011-07/msg00783.html}
1208 @uref{https://lists.gnu.org/archive/html/lilypond-devel/2011-07/msg01004.html}
1209 @uref{https://lists.gnu.org/archive/html/lilypond-devel/2011-08/msg00117.html}
1213 @node GOP-PROP 7 - developers as resources
1214 @subsubsection GOP-PROP 7 - developers as resources
1216 We shall treat developers (and contributors) as
1217 @strong{Independent volunteers}: each person does whatever they
1218 want, whenever they want. We have busy careers and lives; we make
1219 no expectations of action from anybody (with the exception of the
1220 6 people in @qq{Meister} positions).
1222 @subsubheading Discussions
1225 @uref{https://lists.gnu.org/archive/html/lilypond-devel/2011-07/msg01092.html}
1226 @uref{https://lists.gnu.org/archive/html/lilypond-devel/2011-08/msg00087.html}
1227 @uref{https://lists.gnu.org/archive/html/lilypond-devel/2011-08/msg00497.html}
1231 @node GOP-PROP 8 - issue priorities
1232 @subsubsection GOP-PROP 8 - issue priorities
1234 We will delete the @qq{priority} field of the issue tracker
1235 altogether. The @qq{type} system will be tweaked.
1242 a reproducible failure to build either @code{make} or @code{make
1243 doc}, from an empty build tree, in a first run, if
1244 @code{configure} does not report any errors.
1247 any program behaviour which is @strong{unintentionally} worse than
1248 the previous stable version or the current development version.
1249 Developers may always use the @qq{this is intentional}, or even
1250 the @qq{this is an unavoidable effect of an improvement in another
1251 area}, reason to move this to a different type.
1254 anything which stops contributors from helping out (e.g.
1255 lily-git.tcl not working, source tree(s) not being available,
1256 LilyDev being unable to compile git master, inaccurate
1257 instructions in the Contributor's Guide 2 Quick start).
1259 To limit this scope of this point, we will assume that the
1260 contributor is using the latest LilyDev and has read the relevant
1261 part(s) of the Contributor's Guide. Problems in other chapters of
1262 the CG are not sufficient to qualify as Type-Critical.
1266 @subsubheading More new/changed types and labels
1268 Unless otherwise specified, the current types and labels will
1269 continue to be used. The new types introduced by this proposal
1275 Type-crash: any segfault, regardless of what the input file looks
1276 like or which options are given. Disclaimer: this might not be
1277 possible in some cases, for example certain guile programs (we
1278 certainly can't predict if a piece of scheme will ever stop
1279 running, i.e. the halting problem), or if we rely on other
1280 programs (i.e. ghostscript). If there are any such cases that
1281 make segfault-prevention impossible, we will document those
1282 exceptions (and the issue will remain as a "crash" instead of
1283 "documentation" until the warning has been pushed).
1286 Type-maintainability: anything which makes it difficult for
1287 serious contributors to help out (e.g. difficult to find the
1288 relevant source tree(s), confusing policies, problems with
1289 automatic indentation tools, etc).
1292 Type-ugly: replaces Type-collision, and it will include things
1293 like bad slurs in addition to actual collision.
1297 A new label will be added:
1301 (label) Needs_evidence: it is not clear what the correct output
1302 should look like. We need scans, references, examples, etc.
1306 @subheading Reminding users about stars
1308 We can remind users that they can @qq{star} an issue to indicate
1309 that they care about it. Since we resolved to treat developers as
1310 independent volunteers, there is no expectation that anybody will
1311 look at those stars, but if any developer want to organize their
1312 work schedule according to the stars, they are welcome to do so.
1314 @subsubheading Discussions
1317 @uref{https://lists.gnu.org/archive/html/lilypond-devel/2011-08/msg00019.html}
1318 @uref{https://lists.gnu.org/archive/html/lilypond-devel/2011-08/msg00277.html}
1319 @uref{https://lists.gnu.org/archive/html/lilypond-devel/2011-08/msg00413.html}
1320 @uref{https://lists.gnu.org/archive/html/lilypond-devel/2011-08/msg00624.html}
1325 @node GOP-PROP 9 - behavior of make doc
1326 @subsubsection GOP-PROP 9 - behavior of make doc
1328 If there are build problems, then it should be easier to find out
1329 why it's failing. This will be achieved with log files, as well
1330 as possibly including scripts which automatically display portions
1331 of those log files for a failing build.
1333 We will also add targets for building a specific manual (for
1334 quick+easy checking of doc work), as well as for building all
1335 documentation in a specific language (either English or a
1336 translated language).
1338 When you run @code{make doc},
1343 All output will be saved to various log files, with the exception
1344 of output directly from @code{make(1)}.
1346 Note that @code{make(1)} refers to a specific executable file on
1347 unix computers, and is not a general term for the build system.
1350 By default, no other output will be displayed on the console, with
1351 one exception: if a build fails, we might display some portion(s)
1352 of log file(s) which give useful clues about the reason for the
1355 The user may optionally request additional output to be printed;
1356 this is controlled with the @code{VERBOSE=x} flag. In such cases,
1357 all output will still be written to log files; the console output
1358 is strictly additional to the log files.
1361 Logfiles from calling lilypond (as part of lilypond-book) will go in
1363 @file{$LILYPOND_BUILD_DIR/out/lybook-db/12/lily-123456.log} file. All
1364 other logfiles will go in the @file{$LILYPOND_BUILD_DIR/logfiles/}
1367 A single @code{make doc} will therefore result in hundreds of log
1368 files. Log files produced from individual lilypond runs are not
1369 under our control; apart from that, I anticipate having one or two
1370 dozen log files. As long as it is clear which log file is
1371 associated with which operation(s), I think this is entirely
1372 appropriate. The precise implementation will be discussed for
1373 specific patches as they appear.
1376 Both stderr and stdout will be saved in @code{*.log}. The order
1377 of lines from these streams should be preserved.
1380 There will be no additional @qq{progress messages} during the
1381 build process. If you run @code{make --silent}, a non-failing
1382 build should print absolutely nothing to the screen.
1385 Assuming that the loglevels patch is accepted, lilypond (inside
1386 lilypond-book) will be run with --loglevel=WARN.
1387 @uref{http://codereview.appspot.com/4822055/}
1390 Ideally, a failing build should provide hints about the reason why
1391 it failed, or at least hints about which log file(s) to examine.
1395 If this proposal is accepted, none of these policies will be
1396 assumed to apply to any other aspect of the build system.
1397 Policies for any other aspect of the build system will be
1398 discussed in separate proposals.
1400 @subheading Don't cause more build problems
1402 However, there is a danger in this approach, that vital error
1403 messages can also be lost, thus preventing the cause of the
1404 failure of a make being found. We therefore need to be
1405 exceptionally careful to move cautiously, include plenty of tests,
1406 and give time for people to experiment/find problems in each stage
1407 before proceeding to the next stage.
1409 This will be done by starting from individual lilypond calls
1410 within lilypond-book, and slowly moving to @qq{larger} targets of
1411 the build system -- after the individual lilypond calls are are
1412 producing the appropriate amount of output and this is saved in
1413 the right place and we can automatically isolate parts of a
1414 failing build, we will work on lilypond-book in general, and only
1415 then will we look at the build system itself.
1417 @subheading Implementation notes
1419 There is an existing make variable QUIET_BUILD, which
1420 alter the amount of output being displayed
1422 http://lilypond.org/doc/v2.15/Documentation/contributor/useful-make-variables}
1423 ). We are not planning on keeping this make variable.
1425 The standard way for GNU packages to give more output is with a
1426 @code{V=x} option. Presumably this is done by increasing
1427 @code{x}? If we support this option, we should still write log
1428 files; we would simply print more of the info in those log files
1431 The command @code{tee} may be useful to write to a file and
1432 display to stdout (in the case of VERBOSE).
1435 @subsubheading Discussions
1438 @uref{https://lists.gnu.org/archive/html/lilypond-devel/2011-08/msg00378.html}
1439 @uref{https://lists.gnu.org/archive/html/lilypond-devel/2011-08/msg00703.html}
1444 @n ode GOP-PROP 10 - scheme indentation
1445 @s ubsubsection GOP-PROP 10 - scheme indentation
1447 still under discussion
1449 @subsubheading Discussions
1452 @uref{https://lists.gnu.org/archive/html/lilypond-devel/2011-08/msg00625.html}
1453 @uref{https://lists.gnu.org/archive/html/lilypond-devel/2011-08/msg01026.html}
1460 @node Grand LilyPond Input Syntax Standardization (GLISS)
1461 @section Grand LilyPond Input Syntax Standardization (GLISS)
1467 Start: sortly after 2.14 comes out, which is currently estimated
1468 to happen in January 2011.
1471 Length: 6-12 months. We're not going to rush this.
1474 Goal: define an input which we commit to being
1475 machine-updateable for the forseeable future. Any future patches
1476 which change the syntax in a non-convert-ly-able format will be
1477 rejected. (subject to the limitations, below)
1478 Once this is finished, we will release lilypond 3.0.
1483 @subheading The Problem
1485 One of the biggest complaints people have with lilypond -- other
1486 than silly thing like "there's no gui" -- is the changing syntax.
1487 Now, inventing a language or standards is difficult. If you set
1488 it in stone too soon, you risk being stuck with decisions which
1489 may limit matters. If you keep on updating the syntax,
1490 interaction with older data (and other programs!) becomes complex.
1492 @subheading Scope and Limitations
1496 tweaks will not be included. Anything with \override, \set,
1497 \overrideProperty, \tweak, \revert, \unset... including even those
1498 command names themselves... is still fair game for NOT_SMART
1502 other than that, everything is on the table. Is it a problem to
1503 have the tagline inside \header? What should the default behavior
1507 we need to get standards for command names. This will help users
1508 remember them, and reduce the options for future names (and
1509 potential renamings later on). \commandOn and \commandOff seem to
1510 work well (should we *always* have an Off command?), but what
1511 about the "command" part? Should it be \nounVerbOn, or
1512 \verbNounOn ? Or \verbNotesWithExtraInformationOn ?
1515 we need standards for the location of commands. Ligature
1516 brackets, I'm looking at you. (non-postfix notation must die!)
1519 this Grand Project doesn't affect whether we have a 2.16 or not.
1520 The main problem will be deciding what to do (with a bit of
1521 messiness anticipated for \tuplet); we should definitely release a
1522 2.16 before merging _any_ of these changes.
1525 we obviously can't /guarantee/ that we'll /never/ make any
1526 non-convert-ly changes in the basic format. But we *can*
1527 guarantee that such changes would force lilypond 4.0, and that we
1528 would only do so for overwhelmingly good reasons.
1532 @subheading Workflow
1536 We're going to have lots and lots of emails flying around. The
1537 vast majority won't really fit into either -devel or -user, so
1538 we'll use a list devoted to syntax issues.
1541 Once we have a serious proposal that gained general acceptance
1542 from the separate syntax mailing list, I'll bring it to -devel.
1543 We're not going to make any changes without discussing it on
1544 -devel, but if we're going to have huge threads about English
1545 grammar and silly ideas, and I don't want to clutter up -devel.
1546 Once whatever chaotic silliness on the syntax list is settled
1547 down, I'll bring the ideas to -devel.
1550 as with GDP, I'll moderate the discussion. Not as with mailist
1551 moderation, but rather by introducing issues at specific times.
1552 We don't want a free-for-all discussion of all parts of the syntax
1553 at once; nothing will get resolved.
1556 Whenever possible, we'll decide on policies at the highest level
1557 of abstraction. For example, consider \numericTimeSignature,
1558 \slurUp, \xNotesOn, \startTextSpan, and \verylongfermata. One of
1559 them starts with the name of the notation first (slur). One has
1560 an abbreviation (x instead of cross). One has the verb at the end
1561 (On), another has it at the beginning (start). The adjective can
1562 come at the beginning (numeric, x) or end (Up). Most are in
1563 camelCase, but one isn't (verylongfermata).
1566 Instead of arguing about each individual command, we'll decide on
1567 abstract questions. Should each command begin the notation-noun,
1568 or the verb? Should all commands be in camelCase, or should we
1569 make everything other than articulations in camelCase but make
1570 articulations all lower-case? Are abbreviations allowed?
1573 Once we've answered such fundamental questions, most of the syntax
1574 should fall into place pretty easily. There might be a few odd
1575 questions left ("is it a span, or a spanner?"), but those can be
1576 settled fairly quickly.
1580 @subheading Implementation
1582 Nothing until the project is finished, then we declare the next
1583 stable release (2.16.0 or 2.18.0 ?) to be the final 2.x version,
1584 release it, then apply all the GLISS syntax changes and start
1585 testing a beta for 3.0 a week or two later.
1587 @subheading Discussion
1589 Don't respond to any of the specifics yet. Yes, we all have our
1590 pet irritations (like "what's up with \paper and \layout?!").
1591 There will be plenty of time to discuss them once GLISS starts.
1593 That said, we have a list of specific items that people really
1594 wanted to have written down. See @ref{Specific GLISS issues}.
1597 * Specific GLISS issues::
1601 @node Specific GLISS issues
1602 @subsection Specific GLISS issues
1606 add regtests for every piece of syntax (not one-command-per-file,
1607 but making a few files which, between them, use every single piece
1608 of syntax.) This is a great test for convert-ly.
1611 should GLISS cover suggested conventions? (indentation,
1612 one-bar-per-line, etc -- the kind of stuff we list for the
1613 lilypond formatting in the docs ?)
1616 how much (if any) syntactic sugar should we add? i.e.
1618 \instrumentName #'foo
1620 \set Staff.instrumentName
1622 ? Carl: maybe yes, Neil: no. (for example, it fails for
1626 the values that are used as arguments to common used overrides.
1627 Sometimes they are a symbol (e.g. #'around), sometimes a
1628 predefined variable referring to a Scheme value or object (e.g.
1629 #LEFT, #all-visible ). The main trouble is that for novice users
1630 it is not clear when there should be an apostrophe and when not.
1633 When do we need -\command and when is it just \command ?
1637 Command-line options to the lilypond binary. -dfoo counts as a
1638 tweak; we won't be trying to pin those down.
1651 If would be pedagogically simpler to realize this difference if
1652 the syntax was separate if you define a context from scratch (as
1653 is the case with \RemoveEmptyStaffContext) or if it's defined by
1654 adding onto an existing context. For example, a syntax like
1658 % Copy the current settings of the Staff context:
1660 % do whatever additional settings
1662 %%% could be used to distinguish from
1664 % Take settings from a variable:
1666 % do whatever additional settings
1672 % Start from scratch:
1681 Capitalization of identifiers: \VoiceOne ?
1686 { music expression } * 4
1688 \repeat unfold 4 { music expression }
1693 @uref{http://lists.gnu.org/archive/html/lilypond-devel/2010-04/msg00467.html}
1697 Personally, I find it easier to understand when there's a repeated
1698 8 in the half-bar position; it's much easier to see that you have
1703 %%% instead of one group of eight:
1708 trivially simple bar-lines:
1712 encourage, allow, or discourage, or disallow?
1715 indentation of \\ inside a @{@} construct.
1719 barline checks at the end of line should be preceded by at least 2
1720 spaces? barline checks should line up if possible (i.e. if you
1721 can use less than 4, 8, X empty spaces before a barline check to
1725 Why doesn't \transpose respect \relative mode?
1729 on \score vs. \new Score
1731 But in the light of a consistent syntax and semantic, I see no
1732 reason (from the users POV) to disallow it. After all, the real
1733 top-level context is a \book @{@}, isn't it, and I don't see a point
1734 in disallowing a \new Score construct just like \new Staff.
1736 From a syntactical POV, I see the following pros for \new Score:
1737 - You can write \with @{ ... @} for every other context but \Score,
1738 which (for consistency) should also work with \new Score.
1739 - When there's a \new Foo Bar, there's also a \context Foo Bar,
1740 which makes the same as a parallel instantiation of all Bar's.
1741 - [Quoting Rune from
1742 @uref{http://www.mail-archive.com/lilypond-devel@@gnu.org/msg14713.html}
1743 "I know that the \score-statement is a syntactical construct,
1744 but I think it would be nice to hide this fact from the users. I
1745 think we could make the use of score-block much more intuitive if
1746 changing the syntax to \new \Score and adding an implicit
1747 sequential-statement to the score."
1752 @uref{http://code.google.com/p/lilypond/issues/detail?id=1322}
1753 about \new vs. \context.
1757 Let users add their own items to the parser? comment 11 on:
1758 @uref{http://code.google.com/p/lilypond/issues/detail?id=1322}
1761 should engravers be pluralized (note_heads_engraver) or not
1762 (note_head_engraver) ?
1765 should we allow numbers in identifier names? Issue:
1766 @uref{http://code.google.com/p/lilypond/issues/detail?id=1670}
1769 should we officially allow accented characters? in general, how
1770 do we feel about utf-8 stuff?
1773 for the sake of completeness/simplicity, what about *disallowing*
1774 the "one-note" form of a music expression? i.e. only allowing
1777 \transpose c d { e1 }
1778 \transpose c d << e1 >>
1787 What should be the officially encouraged way of writing music for
1788 transposing instruments? Maybe it should be simplified?
1789 See http://lists.gnu.org/archive/html/lilypond-user/2011-07/msg00130.html
1794 @node Unsorted policies
1795 @section Unsorted policies
1797 @subsubheading Language-specific mailing lists
1799 A translator can ask for an official lilypond-xy mailing list once
1800 they've finished all @qq{priority 1} translation items.
1802 @subsubheading Performing yearly copyright update (@qq{grand-replace})
1804 At the start of each year, copyright notices for all source files
1805 should be refreshed by running the following command from the top of
1812 Internally, this invokes the script @file{scripts/build/grand-replace.py},
1813 which performs a regular expression substitution for old-year -> new-year
1814 wherever it finds a valid copyright notice.
1816 Note that snapshots of third party files such as @file{texinfo.tex} should
1817 not be included in the automatic update; @file{grand-replace.py} ignores these
1818 files if they are listed in the variable @code{copied_files}.
1821 @subsubheading Push git access
1823 Git access is given out when a contributor has a significant
1824 record of patches being accepted without problems. If existing
1825 developers are tired of pushing patches for a contributor, we'll
1826 discuss giving them push access. Unsolicited requests from
1827 contributors for access will almost always be turned down.