X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=Documentation%2Fcontributor%2Fadministration.itexi;h=da8f48276caf3ac59043957dff16cbf60ec176b4;hb=9b2aaea69cc2edf5fd023db2d6d0843f69d75131;hp=547186e85cffc76ee565b6f557fbff1370726b73;hpb=d6532ec38597f228ec5516f81bd5200043b2e5f9;p=lilypond.git diff --git a/Documentation/contributor/administration.itexi b/Documentation/contributor/administration.itexi index 547186e85c..da8f48276c 100644 --- a/Documentation/contributor/administration.itexi +++ b/Documentation/contributor/administration.itexi @@ -163,6 +163,7 @@ difficult tasks. * Motivation:: * Ongoing jobs:: * Policy decisions:: +* Policy decisions (finished):: @end menu @node Motivation @@ -241,7 +242,7 @@ busy with other matters, work in that area grinds to a halt. @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 @@ -277,7 +278,7 @@ We often receive reports of typos and minor text updates to the 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 @@ -294,7 +295,7 @@ chapters 1 and 2 (or be willing to read the docs to find out). 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 @@ -303,14 +304,15 @@ Technical requirements: development environment (such as @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. @@ -319,12 +321,10 @@ should discuss it. We are not going to filter this list; if any 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 @@ -347,7 +347,7 @@ discussion. @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 @@ -360,10 +360,9 @@ away. This is not good. (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) @@ -376,22 +375,6 @@ so, who should be on it? @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 @@ -432,7 +415,7 @@ schools, etc. 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) @@ -476,8 +459,100 @@ Should we change the "structure" / "framework" for bounties? (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. + @node Grand LilyPond Input Syntax Standardization (GLISS) @@ -713,7 +788,9 @@ Capitalization of identifiers: \VoiceOne ? @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 @@ -771,14 +848,39 @@ sequential-statement to the score." @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 @end itemize @@ -801,12 +903,12 @@ the source tree: 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}. @@ -818,4 +920,3 @@ developers are tired of pushing patches for a contributor, we'll discuss giving them push access. Unsolicited requests from contributors for access will almost always be turned down. -