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
@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 135 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
(prep: 2 hours. discuss: 10 hours)
-@item @strong{Precise definition of Critical issues}:
-at the moment, a stable release is entirely dependent on the
-number of Critical issues, but there's some questions about
-precisely what a "Critical issue" should be. We should clarify
-this, in conjunction with a general discussion about how often we
-want to have stable releases, how permissive we want to be about
-patches, etc etc.
+@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)
@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
@item
Discussion on
-http://code.google.com/p/lilypond/issues/detail?id=1322
+@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:
-http://code.google.com/p/lilypond/issues/detail?id=1322
+@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
projects / lilypond.git / blobdiff