Re: mergin web/ with master/

[Graham Percival]

On Sat, Jun 06, 2009 at 11:21:39AM +0200, Jan Nieuwenhuizen wrote:
> Op vrijdag 05-06-2009 om 11:18 uur [tijdzone -0700], schreef Graham
> Percival:
> 
> > Do we need a separate branch (or even repository) for web/ stuff?
> 
> Branch is not helpful, a separate repo has the advantage of
> allowing a simple 'git clone' (like it's meant to be)
> to get either one, without getting 'too much'.
> 
> Developers do not need to get the web pages, translators
> do not need to get all of lily?

Translators *do* need to get all of lily.  At least, they need to
get the docs (they translate this after the webpages, right?).
I've toyed with the idea of splitting off the docs into a separate
repo, but then it becomes much harder -- new features and syntax
changes would require patches to both code/ and docs/.  We
definitely don't want to go that way!

I admit that having a tiny repo to clone is a decent way for
translators to get started quicker... but given that they need to
switch repos after 10-20 hours of work anyway, I don't think this
is a great saving.

> > I propose that we merge this with the main branch.
> > 
> > PRO:
> > + one less branch/repo to track
> 
> What is it that bothers you tracking an additional repo?

To be up-to-date, I need to do a "git pull origin" in two separate
directories.  New (or relatively new) contributors need to create
separate directories to get all the source.  Etc.

This isn't a /major/ issue... although twice now, I've forgotten
to update my lilypond-web dir, resulting in me re-creating patches
that other people had already fixed.

Also, we don't always have both dirs set up.  John and I have told
each other "I don't have newweb/ right now, could you make this
change" at least half a dozen times in the past few years -- we
trade it back and forth, depending on who's reinstalled their OS
the most recently.  :)

> > + easier to fix typos in the web pages
> 
> I do not understand this.  Why is that?

People who don't have newweb/ probably won't download the new git
repo just to fix a typo.  People who have never gotten newweb/
definitely won't download it just to fix a typo.

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.

> I "fear" that it's getting easier to create "tainted" commits,
> ie, commits that do a bugfix in lily, typo in web, etc.
> Ideally, a commit does exactly one thing (so it can be
> backported, or reverted if necessary, with more predictable
> consequences).

If you want, I could crack down on this.  Massively crack down.
...
Come on, tell me to crack down.  You know you want to.  :)


Special warning: Jonathan, we need to talk.

> > + we can direct everybody to look at the CG (no more README in the
> > newweb/ branch)
> 
> Why cannot README's info be moved to the CG now?

I just figured that a repo should have its own instructions.
That's not necessary, though.

> Wouldn't this imply, however, that developers must read/skip through
> translator's info and vice versa?

Developers already need to skip translator info.  Fortunately,
this is already nicely ghettoized in the CG, so it's obvious what
to skip and what not to skip.


> > + allows better integration with the other docs (this is more a
> > post-GOP feature)
> 
> This may be a deciding argument, however.  Can you elaborate on
> this?

It's partly psychological.  Since web is in a separate branch, I
never considered changing it as part of GOP.  This isn't just my
problem; the website contains some truly ancient info (all the
"call for jobs" stuff?), which nobody has fixed.  Granted, for the
past six months I've been telling people not to fix it... but that
still leaves years of neglect.

For the new website, I was going to build as much as possible of
it with texinfo.  This would let us distribute the contents on pdf
and info.  In particular, contents like the first-time use (i.e.
all the "lilypond is like a compiler, not a GUI thing" stuff).
Content like the typographical essay (we currently have two;
that's not optimal).

In general, I wanted to start thinking about the website as part
of the docs -- how easy is it to find information in the combined
web+docs, how do new users progress through it, how can we ensure
that new users already know about the "compiling" nature before
they download the program, etc.

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.


> > CON:
> > - adds 30 megs to the main branch (including the .git dir)
> 
> No problem.  However, it adds 1Gb to the translator's download.
> Isn't that one of the biggest cons?

I don't believe that 1Gb figure.  My lilypond is 488 megs, with
all code built, and the English docs built.  My guess is that the
source alone clocks in at 150-200 megs.

Yes, that's still much more than the 30 meg newweb/ by itself, but
if the translators are going to end up working on the docs
eventually, they might as well get it all at the beginning.

> > - makes translations harder?  (maybe?  ... I don't know if this is
> >   true, but IMO this is the only real reason to avoid doing this)
> 
> probably.  moreover, I feel translators need more consideration
> than developers, esp. if we want to have real good translators
> (ie, not programmers who think they can translate)?

True.  Although we could make the same argument about doc writers.
It would be nice if we could split the docs away from the code,
but I really just can't see that working.

Cheers,
- Graham