Re: mergin web/ with master/

[Graham Percival]

On Sat, Jun 06, 2009 at 01:34:42PM +0200, Jan Nieuwenhuizen wrote:
> Op zaterdag 06-06-2009 om 03:14 uur [tijdzone -0700], schreef Graham
> Percival:
> 
> > > What is it that bothers you tracking an additional repo?
> > 
> > To be up-to-date, I need to do a "git pull origin" 
> 
> You should only need
> 
>    git pull -r
> 
> please *do* use -r, otherwise our repo is full of silly "Merged brange
> foo from .."

*sigh*

That would have been very useful to know six months ago, when I
wrote the first draft of the CG and asked everybody to check it.

What should we do for pushing?  Is
   git push origin
ok, or should it be
   git push
?  (I just checked, and "git push" works... but is that the _best_
option?)

> > in two separate directories.  New (or relatively new) contributors need to 
> > create
> > separate directories to get all the source.  Etc.
> 
> Is it so hard to
> 
>     git config --global url.git+ssh://git.sv.gnu.org/srv/git/.insteadof gnu:
> 
>     git clone gnu:lilypond
>     git clone gnu:lilypond-web  # real soon now (unless your proposal :-)

The initial setup isn't really a problem; currently I just blindly
copy&paste:
    mkdir lilypond; cd lilypond
    git init-db
    git remote add -f -t master -m master origin 
git://git.sv.gnu.org/lilypond.git/
    git checkout -b master origin/master

> ?  Create new directories, I don't understand?

We recommend (and I follow) putting lilypond, web, and
lilypond/translations in separate directories.  It's *much* easier
than messing around with branches.  People -- at least, the people
that are savvy enough to contribute to lilypond -- understand
directories.  A directory that magically contains lilypond source,
website source, or translation source, is an unwelcome
complication.


Basically, the entire CG-git stuff is modeled around the idea that
we want contributors working on lilypond stuff (docs,
translations, bugfixes), *not* working on understanding git stuff.

> > Perfect example: Jonathan.  He's currently the main "small doc
> > fix" guy, but he doesn't have newweb/ and never has, so any fixes
> > to the website waits for other people to do.
> 
> Okay, I see.  Well, we agree that the current setup is really
> bad.  I suppose Jonathan could be taught how to handle a separate
> lilypond-web repo?

Of course he _could_ be... although from a functional standpoint,
that's identical to the current CG-recommended setup.  The problem
is that we very rarely have a website fix that's important enough
to warrant the bother of setting it up and learning how it's
organized.

Unless we specifically say "ok, X, you're now in charge of fixing
typos on the website", X is very likely to say "nah, I'm not going
to bother fixing this typo report; I'll let somebody else handle
it".

I know this very well, since I've been X at least half the time.
:)

> > I'm still not certain that it's worth doing it in texinfo.  Many
> > projects these days distribute html files as docs, so we might go
> > with a relatively small set of html files, plus the pdf/info/html
> > "general info" docs (most of the current website), plus the normal
> > docs.
> 
> ...but this choice is not necessarily bound to the one/two repo
> issue.  One repo would enable us to experiment with using texinfo
> here and there...  I'm not sure that would help.

The actual experiments would be done on a separate branch -- but
only the initial experiments.  Basically, I want to:
- merge web/ and master/
- copy the new master/ into gop/
- work on gop/ for 3-4 weeks
- merge gop/ to master, then delete gop/

In the long term, we would only have a single master/ branch, plus
the various temporary/private development branches.

(yes, something would happen to gub-samco and lilypad-macos).

> > True.  Although we could make the same argument about doc writers.
> 
> Why is that?

Explaining how to use lilypond is no more technically challenging
than translating an explanation into another language.  Yes, to
write good docs, you need to understand the material involved --
but that's quite distinct from being able to figure out texinfo,
git, and the like.

We *have* lost documentation writers due to our choice of texinfo
as the documentation language.  It's confusing, limited, and not
at all friendly to learn.

*shrug*

I'm not saying that the people we lost were absolutely
fantastic... since they never really started, I can't tell,
obviously.  :)   And I'm definitely not saying that there's a
better language that produces good pdf+html (frankly, I couldn't
care less about info).

I'm also not saying that a certain amount of upfront difficulty is
a *bad* thing.  Somebody could make the argument that if a
potential contributor isn't willing to learn texinfo + git +
making functional diffs + our policies, then they don't have the
dedication to be a good contributor anyway.

I'm *not* making this argument myself.  Rather, I'd say that if
somebody can't figure out the CG -- as long as we make the
repositories, branches, and CG as easy to follow as possible --
then they probably would not be a net contributor.  But if I'm
going to feel good about rejecting (apparently) sincere offers of
help, then I want to be maoing certain that the CG (and git repos,
branches, etc) **are** as easy to follow as possible.

Cheers,
- Graham