Improving the Contributors Guide and LilyDev

[Paul Morris]

Hello dev list,

Below are some notes I made as I worked with the contributor’s guide and 
LilyDev in recent months.  This started with minor things and grew from there.  
They represent my view as a novice who is basically learning git and the 
command line as I go.  I found the learning curve pretty steep so even little 
things that make things easier would help.

I was planning on preparing patches for some of these items when I can get to 
it, others are suggestions and possible topics for discussion.  Janek’s 
interest in working on this inspired me to go ahead and type it up.

-Paul


A. Suggestions for LilyDev3:

Make nano the default editor for git, git-cl, and anywhere else needed.  This 
might be the simplest single thing that would improve the learning curve.  
Those who like another more advanced editor like vim will likely know how to 
set it as their default.  (And/or in the CG walk the reader through the steps 
to change the editor settings.)

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)$ "

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.)

Automatic formatting/indenting of C++ files currently doesn't work "out of the 
box” and there’s no easy way to manually get it to work.  Artistic Style 2.02 
is required for LilyPond’s fixcc.py but LilyDev3 has 2.01, which is the version 
provided by Debian and the only version available through apt-get.  Version 
2.02 is no longer available from SourceForge.  Possible solution: make fixcc.py 
work with Artistic Style 2.01 (Federico wrote that LilyDev will provide the 
default Debian version of Artistic Style so that rules out upgrading it to 
2.02.)  (Another possible solution: does LilyPond need its own formatting style 
or would the GNU one work fine and avoid this maintenance/overhead?)


B. CG Notes 

CG 2.1 Installing LilyDev in VirtualBox
Just for extra clarity, change: 
"Click the browse icon and locate the LilyDev disk image…" 
To: 
"Click the browse icon and locate the LilyDev disk image file (the .iso file) 
that you downloaded…"

CG 3.3.4 Making Patches
"git format-patch origin" doesn't work if you type it in literally, but gives 
"ambiguous argument 'origin' " message.  Change it to "git format-patch 
origin/master" which I assume is the most common case.

CG 3.3.4 duplication typo under git-cl configuration:
  2. Move into the top source directory and then configure git cl with the 
following commands:
  3. Move into the top source directory and then configure git cl with the 
following commands:

CG 3.3.4 I think "git-cl install" should go elsewhere, where setup is covered, 
especially since it's already installed on LilyDev.

CG 3.3.4 git-cl configuration
add how to set the EDITOR variable for git cl, namely:
export EDITOR=/usr/bin/nano

Somewhere document how to access ~/.bashrc ( such as "nano ~/.bashrc" ) to see 
what environment variables are set, etc.

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)
2. Compiling with LilyDev (2.3) and Compiling (4.x)


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.

The reader may need some help with certain command line tasks.  Go ahead and 
provide the literal command to type in when it is easy to do so, rather than 
assume the reader knows it already or should go look it up somewhere else.  
(For example how to change the default editor.)