Re: doc branching

[Han-Wen Nienhuys]

Graham Percival wrote:
> >  2. -> we've been trying to do this for ages, and for the 2.8 it's 
> > almost worked (9 months).
> >
> > The real problem is that all hackers should agree on a single period 
> > were nothing but bugfixing happens. It might be  a good thing to just 
> > use the Linux 2.6 model, where we have a fixed period in time to merge 
> > new functionality and then a cool-off period to fix bugs, and more 
> > rapid cycles.
>
> Sorry, I thought the Linux 2.6 model was to change the whole VM system 
> in between .10 and .11 ?  ... or was that the Linux 2.4 model?  :-)

:)

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

> >  3. -> This shouldn't be too hard if the number of sync points is 
> > small. You can just run a diff between older versions and apply the 
> > diff to 2.8; big problem: this doesn't work when we change the syntax 
> > radically.
>
> Changing syntax, and new features.  For example, just today I had to 
> comment out the input/regression/hairpin-circle.ly  file so that I could 
> test the most recent doc fixes.  That's not a big deal if it's stuff in 
> the NEWS or input/ , but removing stuff from the doc patches is a huge 
> pain.  I think I did it twice in the early 2.7 -> 2.6 phase before 
> giving up.

Hmmm; part of the problem might also stem from using CVS, which doesn't 
have good cherry-picking for patches.

> >  4. -> I oppose of this. In the ideal world, each release, including 
> > every 2.9.x, is a fully self-contained, 'finished' release.
>
> In an ideal world, we have a team of 25 uber-hackers working on lilypond 
> full-time.  :)   The question is how to best utilize the resources we have.
>
> >  Allowing documentation to go out of date further raises the barrier 
> > to doing a "stable" releases, and we want that barrier to go down, 
> > instead of up.
>
> 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 really think that doing all this at once will result in less work, not 
> more, and will present no extra barrier to release.

ok.

> > Perhaps we can come to a hybrid? Ie.
> >
> >  - 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. 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.

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.

--

Han-Wen Nienhuys - address@hidden - http://www.xs4all.nl/~hanwen

LilyPond Software Design
 -- Code for Music Notation
http://www.lilypond-design.com