Re: doc branching

[Graham Percival]

On 5-Apr-06, at 2:51 AM, Han-Wen Nienhuys wrote:

> Graham Percival wrote:
> > 2.  Much shorter devel periods (say, four months).  New users still 
> > get confused and ask questions about things which I've already 
> > clarified,
> >
> > 3.  Once a month, somebody goes through the tiresome process of 
> > sifting through differences between the devel and stable manuals, and 
> > backports whatever is appropriate.  If somebody wants to volunteer to 
> > do this, fine; I'm not willing to do it.
> > 4.  For the first half of the development cycle, don't include new 
> > features in the manual.  New things get listed in NEWS, but only 
> > there.
>
> my preference in order of desirability:
>
>  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)

One of the background issue prompting this is that I'll have a lot of 
time to work on doc stuff, starting in about two weeks.  I'd really 
like to get those changes into the stable manual, so we don't have 
another eight months of "please read the 2.9 manual, even though you're 
using 2.8".  So if this bug-fixing stage lasts for a month or so (I 
don't know what this might mean for Erik's music streams, though), I'm 
fine.


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

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

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

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

- Graham