Re: improving the CG

[Graham Percival]

On Fri, Dec 25, 2009 at 09:04:29PM -0700, Carl Sorensen wrote:
> 
> On 12/25/09 8:13 PM, "Mark Polesky" <address@hidden> wrote:
> 
> > Carl Sorensen wrote:> As I think more about this, I wonder if there should 
> > be
> > a
> >> short and sweet summary for experienced Linux developers,
> >> followed by a gentle (and longer) introduction for the
> >> Windows guys.
> 
> I still think you should have a quick-start guide for people who are already
> experienced with Linux development and git, so that they can quickly find
> out what is special/unique to LilyPond development.

I like this idea, but I'm not certain if we all have the same
idea.  Here's the idea that I like:

1. introduction

1.1 help us: duplicate material from website

1.2 summary for unix developers: 2-3 paragraphs.  We use git, the
docs are in git and generated with texinfo, we use google issue
tracker, more details later in this manual, full stop.

1.3 summary for other contributors: 1-1.5 pages; the introduction
that Mark has already written.


> I'm glad you think the LGCG (LilyPond Git Contributor's GUI) is "pretty
> awesome".  You have Graham to thank for that, as he kept the development
> focused.
>
> There is *no* documentation for the LGCG.  You're welcome to write it.  I
> wasn't planning to.

I'm not totally sold on the LGCG name; I think "lilycontrib" is
better, although still not ideal.

Speaking of focused, it would be great if Mark could write docs
for it.  Something like 1 page?  I don't think we need any
screenshots -- first, the UI could well change in the near future,
and second, I think the tool is simple enough that we don't need
any.

Anyway, while you do this, Mark, please keep an eye out for
problems in lilycontrib -- is something unclear; is it possible
for somebody to lose their work or generate a bad patch, etc.  One
notion that I considered was whether we wanted to get more
instructions for writing the log message... something like:

Summary: write one line, no longer than this one.
_________________________________________________
Details: write as much as you want.
_________________________________________________
_________________________________________________
_________________________________________________
_________________________________________________
_________________________________________________

the script would then automatically add the blank line between the
summary and details, and make the real commit message.\

(yes, it took me a minute to get exactly 50 characters for the
Summary line.  :)


I'm not certain if it's worth doing this or not... we'd also need
to make sure that the font for the "summary" line was fixed-width.
OTOH, this could be a fun little extra feature to add to the
script.


> Have you considered whether "Using Git" should be an appendix?  To the
> extent that it's teaching about git, rather than about LilyPond, it might
> belong in an appendix.
> 
> Maybe there should be a chapter called something like "Contributing patches"
> that mentions all the possible ways of contributing patches, and then
> appendices describing various ways (diff, git, lilycontrib.tcl).

Speaking of focus, I'm getting a bit concerned about feature
creep.  My initial reaction is that anything that would be
appropriate to have in a separate appendix about git could be
replaced with "To learn more about XYZ, see the git documentation
or one of the many git tutorials".

The lilycontrib script has released a *huge* amount of pressure on
the git stuff in the CG.  The biggest hurdle that new contributors
faced was git; now that people (especially non-technical doc
writers and translators) can do all their gitting with literally
three clicks, I think it's time to look at who's left: technical
people who want to do fancier stuff.

I still think that things like the cut&paste setup are
appropriate.  "git help remote" says, and I quote,

           git-remote add [-t <branch>] [-m <master>] [-f]
[--mirror] <name> <url>
...
       add
           Adds a remote named <name> for the repository at <url>.
The command
           git fetch <name> can then be used to create and update
           remote-tracking branches <name>/<branch>.

Going from that description to
  git remote add -f -t master -m master origin \
    git://git.sv.gnu.org/lilypond.git/
isn't particularly easy.

But for other things -- including, I must admit, stuff that I
added like "git am" -- is it really appropriate to describe them
in the CG?  I'm wondering if we could replace most of the current
material with a table of "commonly used" or "recommended"
commands... kind-of like the "syntax summary" of texinfo in the
doc chapter.
  applying patches: git am, or git apply (for badly made ones)
  branches: git branch
  browsing history: gitk
  searching: git grep
  status: git status
  reset: git reset, or "git reset --hard origin/master".  warning:
this is the "nuke everything" option; you will lose your work.

  For more information about these commands, see @ref{Other git
documentation}.
 

As far as I know, all the lilypond developers apart from me have
read various git documentation or tutorials, and they seem to be
doing just fine with it.  If somebody wants the power and
flexibility of command-line git, I don't think it's inappropriate
to ask them to read dedicated documentation for that, as long as
we give them a few pointers about what commands they want.

If you think this is a change in my position... well, yes and no.
My main concern has always been the people who *don't* want the
power and flexibility of git; people who just want to fix a few
typos on the webpage and then get on with life.  My second concern
is myself, but I think I've picked up enough git to get by.  And
if I start whining about the difficulty of "git am" in the future,
I invite everybody to tell me to either man up and read the git
docs, or stop pretending to be capable of mentoring new
contributors.  :)

Cheers,
- Graham