Re: doc branching

[Graham Percival]

On 5-Apr-06, at 4:49 AM, Han-Wen Nienhuys wrote:

> Graham Percival wrote:
> > If the hackers are fine with this, I'm certainly happy with this 
> > solution.  I take it that we're still in the bug-fixing stage?  
> > (since 0 recently came out, we have a lot of new interest, finding 
> > more bugs, pointing out more doc stuff, etc)
>
> Errmmh, no, we had the bugfixing stage before the 2.8.0 release. In 
> 2.8   we only fix regression bugs, and I don't remember seeing any of 
> those yet.

Well, there's some kind of mysterious bug on windows that's causing 
problems, isn't there?  (ok, that doesn't narrow it down much :)    I 
was considering installer/running issues as bugs, rather than 
traditional lily bugs (ie notation).

Whatever you want to call the situation with lilypond itself, I'm still 
getting a lot of small fixes for the docs -- as expected from a new 
stable release.

> > Adding all the new features (at least, all the new features which IMO 
> > were worth being in the manual) from the 2.8 NEWS file would take me 
> > less than six hours.  It would probably be two, but I'm being 
> > conservative in my estimate.  Updating the documentation syntax is 
> > just a matter of convert-ly  -- and in the case of the 3.0 change, 
> > perhaps some manual stuff.  But all that work would need to be done 
> > anyway.
>
> Maybe the real problem is that we're about to have a release with both 
> major functionality (Joe's page breaking patches, Erik's music streams 
> etc.) and scheduled syntax maintenance. Perhaps we ought to do those 
> in two separate releases  (2.10 and then a 3.0).

I'm always in favor of smaller releases... particularly in this case.  
Before breaking the syntax, we should make sure that we do all the 
breakage we can.  Err, that didn't come out right.  :)   I mean that we 
should do it all at once.

In addition, if Erik's music streams are in place in 2.10, then users 
who don't want to manually upgrade syntax on old completed files have 
the option of using the streams (which is the whole point of them, 
right?)   If you look at it that way, wouldn't we be absolutely crazy 
to release 3.0 instead of 2.10?  :)

> > I really think that doing all this at once will result in less work, 
> > not more, and will present no extra barrier to release.
>
> ok.

Thinking about it more, it probably would cause a fair amount of havoc 
in a 2.x->3.0 release.  But I'm certain that it will work well for 2.x 
or 3.x releases.  I'll just have to make sure the manual is perfect for 
2.10, so I don't need to change anything in between 2.10 and 3.0.

> > >  - improve the 2.9 manual only with documentation for new 
> > > functionality
> > >  - improve the 2.8 manual only for things that didn't change in 2.9
> > >  - front-port the 2.8 documentation patches to 2.9 every once in a 
> > > while.
> > Err... yuck?  I really don't want to be working on two large 
> > documents at once.  If you want, I could only improve things for 2.8 
> > that didn't change in 2.9, and you could improve the 2.9 manual with 
> > new functionality and front-port 2.8 patches.  But I don't think you 
> > want to be doing more work.  :)
>
> That doesn't sound so bad actually.

Maybe it's just my inexperience with diff/cvs...

>  The mode of working could be: people contributing 2.9 material make 
> rough-draft documentation, which will be in an appendix "New 
> functionality". Relevant parts of the main manual get a single 
> "Changed in 2.9 see Appendix X" marker.

Isn't this exactly what the NEWS does?  Ok, I guess NEWS is a bit light 
on details... but this was essentially my initial idea.  If people are 
submitting more in-depth documentation, then that certainly makes my 
life easier.

> Then, when we gear up for 2.10 / 3.0 release, and you overwrite the 
> manual with the 2.8 version, and then distribute the 2.9 material over 
> the new manual.

Exactly!  ... actually, this could work even better than I originally 
thought -- if I only make changes to the 2.8 docs, I don't need to 
track unstable lily (and its various little hiccups, like new 
functionality in CVS and docs that I can't compile until a new unstable 
GUB release).

- Graham