The Contributor's Guide as a whole is still a work in progress,
but some chapters are much more complete than others. Chapters
which are @qq{almost finished} should not have major changes
-without a discussion on @code{-devel}; in other chapters, a
+without a discussion on @w{@code{-devel}}; in other chapters, a
disorganized @qq{wiki-style dump} of information is encouraged.
Do not change (other than spelling mistakes) without discussion:
@item
Frog Meister: is responsible for code patches from (relatively)
inexperienced contributors. Keeps track of patches, does initial
-reviewing of those patches, sends them to @code{-devel} when
+reviewing of those patches, sends them to @w{@code{-devel}} when
they've had some initial review on the Frog list, pesters the
-@code{-devel} community into actually reviewing said patches, and
+@w{@code{-devel}} community into actually reviewing said patches, and
finally pushes the patches once they're accepted. This person is
@emph{not} responsible for training new programmers, because that
would be far too much work -- he job is @qq{only} to guide
* Motivation::
* Ongoing jobs::
* Policy decisions::
+* Policy decisions (finished)::
@end menu
@node Motivation
@item Consultant:
LilyPond is sometimes critized for not listening to users, but
whenever we ask for opinions about specific issues, we never get
-enough feedback. This is somewhat aggrevating.
+enough feedback. This is somewhat aggravating.
We need a group of users to make a dedicated effort to test and
give feedback. If there's new documentation, read it. If there's
an experimental binary, download it and try compiling a score with
documentation. It would be great if somebody could create
properly-formatted patches for these corrections.
-Technical requirements: ability to run @ref{Lilybuntu}.
+Technical requirements: ability to run @ref{Lilydev}.
@item LSR editor:
LSR contains many useful examples of lilypond, but some snippets
often find them in Ponds of Lilies) and new feature implementors.
Technical requirements: development environment (such as
-@ref{Lilybuntu}), ability to read+write scheme and/or C++ code.
+@ref{Lilydev}), ability to read+write scheme and/or C++ code.
@end itemize
@subsection Policy decisions
There are a number of policy decisions -- some of them fairly
-important -- which we have been postponing for a few years. When
-GOP begins, we will start discussing them.
+important -- which we have been postponing for a few years. We
+are now discussing them slowly and thoroughly; agenda and exact
+proposals are online:
-@warning{The fact that we are not arguing about them right now is
-not, I repeat @strong{not}, an indication that we do not feel that
-these issues are not important. It is simply that if we began
-talking about them now, it would postpone the 2.14 release for a
-few months.}
+@example
+@uref{http://lilypond.org/~graham/gop/index.html}
+@end example
+
+Below is a list of policies which are not @qq{on the agenda} yet.
Note that the presence of an item on this list does @emph{not}
mean that everybody thinks that something needs to be done.
developer thinks we should discuss something, just add it to the
bottom of the list. (the list is unsorted)
-Once GOP starts, the list will be sorted into a rough agenda. We
-will probably introduce one topic each week -- yes, it will
-therefore take months to get through everything, but we must
-balance productive work vs. policy administration. If we find
-that we settle questions faster (or slower) than predicted, we
-will of course change the speed of new topic introductions.
+As GOP progresses, items from this list will be put on the agenda
+and removed from this list. I generally try to have one month's
+discussion planned in advance, but I may shuffle things around to
+respond to any immediate problems in the developer community.
There are some item(s) not displayed here; these are questions
that were posed to me privately, and I do not feel justified in
@warning{The estimated time required for "prep work", and the
following discussion, has been added to each item. At the moment,
-there is an estimated 30 hours of prep work and 125 hours of
+there is an estimated 30 hours of prep work and 140 hours of
discussion.}
@itemize
(prep: 2 hours. discuss: 10 hours)
-@item @strong{Lessons from the 2.14 release; future release policy}:
-What went well; what went badly? (how) should we change any
-policies pertaining to releases? Should an undocumented new
-feature count as release-blocking?
+@item @strong{Future release policy}:
+(how) should we change any policies pertaining to releases? Should
+an undocumented new feature count as release-blocking?
(prep: 1 hour. discuss: 15 hours)
@item @strong{Hackers B}:
-@item @strong{Code style}:
-New contributors sometimes struggle to follow our indentation and
-code style -- this is especially difficult when parts of our
-existing source code doesn't have a consistent style. This is
-problematic... we want new contributors to be struggling with the
-lilypond architecture, not playing games in their text editors!
-(ok, we don't actually want them to be struggling with lilypond
-internals... but given the current state of the CG, it's
-understandable, and at any rate it's still better than struggling
-with code style)
-Speaking academically, C++ code style is a "solved problem". Let's
-pick one of the existing solutions (probably either astyle,
-uncrustify, or emacs), and let a computer deal with this.
-
-(prep: 5 hours. discuss: 15 hours)
-
@item @strong{Git repository(s)}:
We currently have a web/ branch in our main repo; this seems
misleading to new developers. More generally, should we have
We currently have a mix of official GNU mailing lists and lilynet
lists. Is there a strong rationale for having separate mailing
list servers? Why not pick one place, and put all our lists there?
-(or at least, all "permenant" lists?)
+(or at least, all "permanent" lists?)
(prep: 1 hour. discuss: 5 hours)
(prep: 2 hours. discuss: 10 hours)
+@item @strong{Separate branches for active development}:
+it might be good to have @emph{everybody} working on separate
+branches. This complicates the git setup, but with sufficient
+logic in lily-git.tcl, we can probably make it transparent to
+newbies. However, we'd need a reliable person to handle all the
+required merging and stuff.
+
+(prep: 2 hours. discuss: 10 hours)
+
+@item @strong{When do we add regtests?}:
+There is a discrepancy between our stated policy on adding
+regtests, and our actual practice in handling bugs and patches.
+Clarify.
+
+There is also a wider question how to organize the regtests, such
+as where to put interesting-console-output regtests, including
+stuff like lilypond-book and midi2ly in a sensible manner, and
+possibly including regtests for currently-broken functionality.
+
+(prep: 2 hours. discuss: 5 hours)
+
+@item @strong{code readability}:
+"Our aim when producing source code for Lilypond in whatever
+language is that it should be totally comprehensible to a
+relatively inexperienced developer at the second reading."
+
+Rationale:
+- aids maintainability of code base
+- "second reading" so newer developers can look up unfamiliar
+ stuff
+- will help to keep things simple, even if the code is doing
+ complex stuff discourages "secret squirrel" coding, e.g. "how
+ much functionality can I squeeze into as few characters as
+ possible" "comments are for wimps"
+- will aid not *discouraging* new developers to join the project
+
+(prep: 2 hours. discuss: 10 hours)
+
+@item @strong{C++ vs. scheme}:
+what should be in scheme, what should be in C++, what can/should
+be ported from one to the other, etc. Questions of
+maintainability, speed (especially considering guile 2.0), and the
+amount of current material in either form, are important.
+
+(prep: 5 hours. discuss: 15 hours)
+
+@item @strong{always make an issue number for patches}:
+there is a proposal that we should always have a google code issue
+number for every patch. This proposal is closely tied to our
+choice of patch review tool; if we switch to a different tool (as
+suggested in a different proposal), this proposal may become moot.
+
+(prep: 1 hour. discuss: 5 hours)
+
+@item @strong{initalizer lists}:
+shoudl we use initalizer lists for C++? AFAIK they make no
+difference for built-in types, but there's some weird case where
+it's more efficient for objects, or something.
+
+Probably not worth making this a weekly thing on its own, but we
+can probably wrap it up with some other code-related questions.
+
+(prep: 15 minutes. discuss: 3 hours)
+
+@end itemize
+
+@node Policy decisions (finished)
+@subsection Policy decisions (finished)
+
+@subheading GOP-PROP 1: python formatting
+
+We will follow the indentation described in PEP-8.
+@uref{http://www.python.org/dev/peps/pep-0008/}
+
+@itemize
+@item
+use 4 spaces per indentation level
+
+@item
+never mix tabs and spaces (for indentation)
+
+@item
+Code indented with a mixture of tabs and spaces should be
+converted to using spaces exclusively
+
+Once this is done, we should add @code{python -tt} to the build
+system to avoid such errors in the future.
+
@end itemize
+There should be absolutely no tab characters for indentation in
+any @code{.py} file in lilypond git. All such files should be
+converted to use spaces only.
+
+
+@subheading GOP-PROP 2: mentors and frogs
+
+Nothing much was decided. The list of responsibilities was
+slightly altered; see the new one in @ref{Mentors}. We should
+encourage more use of the Frogs mailing list. There's a list of
+contributor-mentor pairs in:
+
+@smallexample
+@uref{https://github.com/gperciva/lilypond-extra/blob/master/people/mentors.txt}
+@end smallexample
+
+That's pretty much it.
@node Grand LilyPond Input Syntax Standardization (GLISS)
@section Grand LilyPond Input Syntax Standardization (GLISS)
+@subheading Summary
+
+@itemize
+@item
+Start: sortly after 2.14 comes out, which is currently estimated
+to happen in January 2011.
+
+@item
+Length: 6-12 months. We're not going to rush this.
+
+@item
+Goal: define an input which we commit to being
+machine-updateable for the forseeable future. Any future patches
+which change the syntax in a non-convert-ly-able format will be
+rejected. (subject to the limitations, below)
+Once this is finished, we will release lilypond 3.0.
+
+@end itemize
+
+
+@subheading The Problem
+
+One of the biggest complaints people have with lilypond -- other
+than silly thing like "there's no gui" -- is the changing syntax.
+Now, inventing a language or standards is difficult. If you set
+it in stone too soon, you risk being stuck with decisions which
+may limit matters. If you keep on updating the syntax,
+interaction with older data (and other programs!) becomes complex.
+
+@subheading Scope and Limitations
+
+@itemize
+@item
+tweaks will not be included. Anything with \override, \set,
+\overrideProperty, \tweak, \revert, \unset... including even those
+command names themselves... is still fair game for NOT_SMART
+convert-ly updates.
+
+@item
+other than that, everything is on the table. Is it a problem to
+have the tagline inside \header? What should the default behavior
+of \include be? When we abolish \times, do we move to \tuplet 3:2
+or \tuplet 2/3 or what (for typical triplets in 4/4 time)?
+
+@item
+we need to get standards for command names. This will help users
+remember them, and reduce the options for future names (and
+potential renamings later on). \commandOn and \commandOff seem to
+work well (should we *always* have an Off command?), but what
+about the "command" part? Should it be \nounVerbOn, or
+\verbNounOn ? Or \verbNotesWithExtraInformationOn ?
+
+@item
+we need standards for the location of commands. Ligature
+brackets, I'm looking at you. (non-postfix notation must die!)
+
+@item
+this Grand Project doesn't affect whether we have a 2.16 or not.
+The main problem will be deciding what to do (with a bit of
+messiness anticipated for \tuplet); we should definitely release a
+2.16 before merging _any_ of these changes.
+
+@item
+we obviously can't /guarantee/ that we'll /never/ make any
+non-convert-ly changes in the basic format. But we *can*
+guarantee that such changes would force lilypond 4.0, and that we
+would only do so for overwhelmingly good reasons.
+
+@end itemize
+
+@subheading Workflow
+
+@itemize
+@item
+We're going to have lots and lots of emails flying around. The
+vast majority won't really fit into either -devel or -user, so
+we'll use a list devoted to syntax issues.
+
+@item
+Once we have a serious proposal that gained general acceptance
+from the separate syntax mailing list, I'll bring it to -devel.
+We're not going to make any changes without discussing it on
+-devel, but if we're going to have huge threads about English
+grammar and silly ideas, and I don't want to clutter up -devel.
+Once whatever chaotic silliness on the syntax list is settled
+down, I'll bring the ideas to -devel.
+
+@item
+as with GDP, I'll moderate the discussion. Not as with mailist
+moderation, but rather by introducing issues at specific times.
+We don't want a free-for-all discussion of all parts of the syntax
+at once; nothing will get resolved.
+
+@item
+Whenever possible, we'll decide on policies at the highest level
+of abstraction. For example, consider \numericTimeSignature,
+\slurUp, \xNotesOn, \startTextSpan, and \verylongfermata. One of
+them starts with the name of the notation first (slur). One has
+an abbreviation (x instead of cross). One has the verb at the end
+(On), another has it at the beginning (start). The adjective can
+come at the beginning (numeric, x) or end (Up). Most are in
+camelCase, but one isn't (verylongfermata).
+
+@item
+Instead of arguing about each individual command, we'll decide on
+abstract questions. Should each command begin the notation-noun,
+or the verb? Should all commands be in camelCase, or should we
+make everything other than articulations in camelCase but make
+articulations all lower-case? Are abbreviations allowed?
+
+@item
+Once we've answered such fundamental questions, most of the syntax
+should fall into place pretty easily. There might be a few odd
+questions left ("is it a span, or a spanner?"), but those can be
+settled fairly quickly.
+
+@end itemize
+
+@subheading Implementation
+
+Nothing until the project is finished, then we declare the next
+stable release (2.16.0 or 2.18.0 ?) to be the final 2.x version,
+release it, then apply all the GLISS syntax changes and start
+testing a beta for 3.0 a week or two later.
+
+@subheading Discussion
+
+Don't respond to any of the specifics yet. Yes, we all have our
+pet irritations (like "what's up with \paper and \layout?!").
+There will be plenty of time to discuss them once GLISS starts.
+
+That said, we have a list of specific items that people really
+wanted to have written down. See @ref{Specific GLISS issues}.
+
+@menu
+* Specific GLISS issues::
+@end menu
+
+
+@node Specific GLISS issues
+@subsection Specific GLISS issues
+
+@itemize
+@item
+add regtests for every piece of syntax (not one-command-per-file,
+but making a few files which, between them, use every single piece
+of syntax.) This is a great test for convert-ly.
+
+@item
+should GLISS cover suggested conventions? (indentation,
+one-bar-per-line, etc -- the kind of stuff we list for the
+lilypond formatting in the docs ?)
+
+@item
+how much (if any) syntactic sugar should we add? i.e.
+@example
+ \instrumentName #'foo
+% instead of
+ \set Staff.instrumentName
+@end example
+? Carl: maybe yes, Neil: no. (for example, it fails for
+pianostaff)
+
+@item
+the values that are used as arguments to common used overrides.
+Sometimes they are a symbol (e.g. #'around), sometimes a
+predefined variable referring to a Scheme value or object (e.g.
+#LEFT, #all-visible ). The main trouble is that for novice users
+it is not clear when there should be an apostrophe and when not.
+
+@item
+When do we need -\command and when is it just \command ?
+
+
+@item
+Command-line options to the lilypond binary. -dfoo counts as a
+tweak; we won't be trying to pin those down.
+
+@item
+@verbatim
+\layout {
+ \context { \Score
+% vs.
+\layout {
+ \context {
+ \Score
+@end verbatim
+
+@item
+If would be pedagogically simpler to realize this difference if
+the syntax was separate if you define a context from scratch (as
+is the case with \RemoveEmptyStaffContext) or if it's defined by
+adding onto an existing context. For example, a syntax like
+
+@verbatim
+\context{
+ % Copy the current settings of the Staff context:
+ \use Staff
+ % do whatever additional settings
+}
+%%% could be used to distinguish from
+\context{
+ % Take settings from a variable:
+ \Variable
+ % do whatever additional settings
+}
+
+%%% and
+
+\context{
+ % Start from scratch:
+ \type ...
+ \name ...
+ \consists ...
+ ...
+}
+@end verbatim
+
+@item
+Capitalization of identifiers: \VoiceOne ?
+
+@item
+@verbatim
+%%% Allow
+{ music expression } * 4
+%%% instead of
+\repeat unfold 4 { music expression }
+@end verbatim
+
+? patch here:
+@smallexample
+@uref{http://lists.gnu.org/archive/html/lilypond-devel/2010-04/msg00467.html}
+@end smallexample
+
+@item
+Personally, I find it easier to understand when there's a repeated
+8 in the half-bar position; it's much easier to see that you have
+two groups of 4:
+
+@example
+c8 c c c c8 c c c
+%%% instead of one group of eight:
+c8 c c c c c c c
+@end example
+
+@item
+trivially simple bar-lines:
+
+c1 | c1 |
+
+encourage, allow, or discourage, or disallow?
+
+@item
+indentation of \\ inside a @{@} construct.
+
+
+@item
+barline checks at the end of line should be preceded by at least 2
+spaces? barline checks should line up if possible (i.e. if you
+can use less than 4, 8, X empty spaces before a barline check to
+make them line up?)
+
+@item
+Why doesn't \transpose respect \relative mode?
+
+
+@item
+on \score vs. \new Score
+
+But in the light of a consistent syntax and semantic, I see no
+reason (from the users POV) to disallow it. After all, the real
+top-level context is a \book @{@}, isn't it, and I don't see a point
+in disallowing a \new Score construct just like \new Staff.
+
+From a syntactical POV, I see the following pros for \new Score:
+- You can write \with @{ ... @} for every other context but \Score,
+which (for consistency) should also work with \new Score.
+- When there's a \new Foo Bar, there's also a \context Foo Bar,
+ which makes the same as a parallel instantiation of all Bar's.
+- [Quoting Rune from
+@uref{http://www.mail-archive.com/lilypond-devel@@gnu.org/msg14713.html}
+ "I know that the \score-statement is a syntactical construct,
+but I think it would be nice to hide this fact from the users. I
+think we could make the use of score-block much more intuitive if
+changing the syntax to \new \Score and adding an implicit
+sequential-statement to the score."
+
+
+@item
+Discussion on
+@uref{http://code.google.com/p/lilypond/issues/detail?id=1322}
+about \new vs. \context.
+
+
+@item
+Let users add their own items to the parser? comment 11 on:
+@uref{http://code.google.com/p/lilypond/issues/detail?id=1322}
+
+@item
+should engravers be pluralized (note_heads_engraver) or not
+(note_head_engraver) ?
+
+@item
+should we allow numbers in identifier names? Issue:
+@uref{http://code.google.com/p/lilypond/issues/detail?id=1670}
+
+@item
+should we officially allow accented characters? in general, how
+do we feel about utf-8 stuff?
+
+@item
+for the sake of completeness/simplicity, what about *disallowing*
+the "one-note" form of a music expression? i.e. only allowing
+stuff like
+@verbatim
+ \transpose c d { e1 }
+ \transpose c d << e1 >>
+@end verbatim
+
+and never allowing
+@verbatim
+ \transpose c d e1
+@end verbatim
+
+@item
+What should be the officially encouraged way of writing music for
+transposing instruments? Maybe it should be simplified?
+See http://lists.gnu.org/archive/html/lilypond-user/2011-07/msg00130.html
+
+@end itemize
@node Unsorted policies
make grand-replace
@end example
-Internally, this invokes the script @file{scripts/@/build/@/grand@/-replace@/.py},
+Internally, this invokes the script @file{scripts/build/grand-replace.py},
which performs a regular expression substitution for old-year -> new-year
wherever it finds a valid copyright notice.
-Note that snapshots of third party files such as @file{texinfo@/.tex} should
-not be included in the automatic update; @file{grand@/-replace@/.py} ignores these
+Note that snapshots of third party files such as @file{texinfo.tex} should
+not be included in the automatic update; @file{grand-replace.py} ignores these
files if they are listed in the variable @code{copied_files}.
discuss giving them push access. Unsolicited requests from
contributors for access will almost always be turned down.
-
projects / lilypond.git / blobdiff