Re: improving the CG

[Carl Sorensen]

On 12/26/09 10:18 AM, "Graham Percival" <address@hidden> wrote:

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

I'm not even a little bit sold on the LGCG name -- it's just what I decided
to put in the window title.

I just don't want it referred to as "the GUI", because of confusion with
git gui.

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

Text width can be set for an input window on tcl; I'm not sure yet
that we can limit the input to that text width.

Do you  think I  should try modifying the commit message window?
> 
> 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 an appendix, I'm fine with having a gentle introduction to git, as long
as Mark is interested in writing it.  It will help people get up to speed on
git more quickly, and may be easier than the git documentation.

Do we need this? Not strictly, because we can always read up on the other
docs.  But if it helps, I'm OK with having it.

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