Re: doc branching

[Han-Wen Nienhuys]

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.

 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.

 4. -> I oppose of this. In the ideal world, each release, including 
every 2.9.x, is a fully self-contained, 'finished' release. 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.

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.

--

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

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