Re: Improving the Contributors Guide and LilyDev

[Carl Sorensen]

On 5/3/15 4:09 PM, "Paul Morris" <address@hidden> wrote:

I think that it would be great to have you prepare patches for the CG.
The CG is the least-reviewed manual in our set, so it's probably the
easiest manual for which to get patches approved.



>
>A. Suggestions for LilyDev3:

All of these suggestions would actually probably be for LilyDev4.  I'm not
sure that we will make another release of LilyDev3.  But if we did, I'm
still happy to host it.

>(And/or in the CG walk the reader through the steps to change the editor
>settings.)

This is an immediately-accessible thing to do.

>
>The indicator of the current git branch (in the command line prompt) is
>not set up in the .bashrc file as it says it is in CG.  This should
>already be set up.  See CG 3.2.1 Configuring Git, where it says:
>  Finally, and in some ways most importantly,
>  let¹s make sure that we know what branch we¹re on.
>  If you¹re not using LilyDev, add this to your Œ~/.bashrc¹:
>  export PS1="address@hidden \w\$(__git_ps1)$ "

Personally, I'd love to see a patch for this in the CG (and it would be
nice to have it in LilyDev out of the box).

>
>Add to LilyDev a text editor that has code highlighting (one that's
>simpler than emacs).  For example LilyDev2 had geany and gedit but
>LilyDev3 doesn't.  (Or at least suggest some as recommended optional
>installs.)

vim has code highlighting, and it is simpler than emacs in my opinion.
But I've been using it for 30 years, since I started with vi.

A CG entry that would tell how to install geany and/or gedit would
certainly be helpful.


>  (Another possible solution: does LilyPond need its own formatting style
>or would the GNU one work fine and avoid this maintenance/overhead?)

GNU's formatting style is less specific in the form of tabs/spaces, IIRC.
We've had this discussion, and I believe it's a good idea to exclude tabs,
and only use spaces in the source code.  astyle isn't needed if you are
careful with your editing and match the existing code. If you make a
mistake, it will be pointed out in review, and it's simple to fix it.

>
>
>B. CG Notes 

Your notes on the CG are excellent in general.  I hope you will prepare
some patches!

>
>In general avoid having sections that basically repeat each other in
>different ways, for example, consider merging:
>1. Git for the impatient (3.2.2) and Basic Git procedures (3.3)

There are reasons (perhaps historical) for this duplication.  3.2.2 is
supposed to be briefer than 3.3.

>2. Compiling with LilyDev (2.3) and Compiling (4.x)

2.3 is about getting it set up with LilyDev.  4.x is about general work
whether with or without LilyDev.  We are much stronger about recommending
the use of LilyDev than we were when the CG was originally written, so
perhaps it's time to make a change here.

>
>
>C. A Few General thoughts FWIW:
>
>Since those working on the documentation, website, or even source code
>may not be programmers but they still have to learn how to use git etc.
>keep non-programmers in mind as a primary audience for the CG.  For
>example:
>
>Assume the reader is using LilyDev.  Those that aren't using LilyDev will
>have more experience and need less from the CG, so better to pitch things
>to those who need the most help.

I'm not sure I agree with this.  The CG is the only place in the manuals
that we provide help for those who are not using LilyDev.  And there are
some quirks of LilyPond that need to be part of the docs in my opinion.

I don't have a particular patch to comment on here, so I can only deal in
generalities.  But maybe we have a chapter that is something about
"Developing without LilyDev".

We certainly want to make the CG accessible for new users/developers.  But
we also want to have the CG useful for old developers and those
experienced with other software development environments.   Perhaps we
need to clarify these two different use cases, and separate them out more
carefully in the CG.  But IMO we need to avoid making the CG only useful
for newbies.

The CG has historically had a much less stringent editorial review
process.  Basically we said to developers "If there's something you think
should go in the CG, put it there."  Perhaps it's time to be more
selective, and see how we can tailor a short, accessible section of the CG
for new users.  And then we could leave the other stuff in chapters that
are aimed at experienced developers.

Thanks again for looking at this.  Certainly improving the CG is an
important part of the health of LilyPond.

Carl