Re: Git repository, was Re: doc branching
Johannes Schindelin escreveu: Hi, On Mon, 23 Oct 2006, Han-Wen Nienhuys wrote: I have some more clues now; some of the time stamps in the CVS repo are messed up; eg revision 1.2 of flower/include/GNUmakefile lists 2002 as the year which is clearly wrong. Most definitely this would trigger a "bug" in cvsps. I say "bug", because really, there are no changesets in CVS, and cvsps just tries to guess which revisions belong together by looking at the timestamp and the commit message. That date is definitely wrong (since the next file revision, 1.3 is in the year 1998 again). It is not only misleading cvsps, but it actually makes the repository less useful. I wonder how you can make that happen, though. It is not like I can edit the date of a file revision with CVS (unless I edit the ,v file). We started using CVS with version 1.5.24, end of 2001. The earlier history has been recreated artificially by importing tarballs with a script. Something went wrong during this process, apparently. -- Han-Wen Nienhuys - [EMAIL PROTECTED] - http://www.xs4all.nl/~hanwen LilyPond Software Design -- Code for Music Notation http://www.lilypond-design.com ___ lilypond-devel mailing list lilypond-devel@gnu.org http://lists.gnu.org/mailman/listinfo/lilypond-devel
Re: Git repository, was Re: doc branching
Hi, On Mon, 23 Oct 2006, Han-Wen Nienhuys wrote: > I have some more clues now; some of the time stamps in the CVS repo are > messed up; eg revision 1.2 of flower/include/GNUmakefile lists 2002 as > the year which is clearly wrong. Most definitely this would trigger a "bug" in cvsps. I say "bug", because really, there are no changesets in CVS, and cvsps just tries to guess which revisions belong together by looking at the timestamp and the commit message. That date is definitely wrong (since the next file revision, 1.3 is in the year 1998 again). It is not only misleading cvsps, but it actually makes the repository less useful. I wonder how you can make that happen, though. It is not like I can edit the date of a file revision with CVS (unless I edit the ,v file). Ciao, Dscho ___ lilypond-devel mailing list lilypond-devel@gnu.org http://lists.gnu.org/mailman/listinfo/lilypond-devel
Re: Git repository, was Re: doc branching
Johannes Schindelin escreveu: Hi, On Mon, 23 Oct 2006, Han-Wen Nienhuys wrote: Interested parties can get the darcs repo at http://lilypond.org/~hanwen/gub-git/ Well, I cannot. As I stated earlier, I gave up on darcs. You can simply wget the directory, which will give you a runnable copy of gub. I found that at least one particular version of git-cvsimport forgot files, but I had the impression that it was because of "--no-rlog". Anyway, I will investigate. (This could take a week or so, as I am travelling.) It might well be a bug in cvsps, or git-cvsimport, or both. Hopefully I can fix it. I have some more clues now; some of the time stamps in the CVS repo are messed up; eg revision 1.2 of flower/include/GNUmakefile lists 2002 as the year which is clearly wrong. -- Han-Wen Nienhuys - [EMAIL PROTECTED] - http://www.xs4all.nl/~hanwen LilyPond Software Design -- Code for Music Notation http://www.lilypond-design.com ___ lilypond-devel mailing list lilypond-devel@gnu.org http://lists.gnu.org/mailman/listinfo/lilypond-devel
Re: doc branching
Johannes Schindelin escreveu: I am tracking the current lilypond repository with git. I could donate this git repository (it is ca. 60MB at the moment). I prefer git over the other alternatives: it is blazingly fast, *very* portable (I gave up on porting darcs after a fruitless day), and branching/merging is an easy operation. I have just updated the GUB builder to work with GIT repository for LilyPond, as an experiment. The goal is that I can work on packaging LilyPond without having to ping-ponging all my changes from my CVS dir via the savannah server to my GUB dir. Interested parties can get the darcs repo at http://lilypond.org/~hanwen/gub-git/ however, I seem to have some trouble with importing the CVS repo into Git. My attempt is at http://lilypond.org/~hanwen/lilypond.git/ This is an rsync of a git repo that is fed by a cvsimport cron job on my home machine. Unfortunately, it seems to be missing some files. Did I botch up the import, or is something wrong with git-cvsimport? $ mkdir y $ cd y $ git --git-dir /home/lilydev/vc/lilypond.git/.git/ log --max-count=1 | grep commit commit 4098351f3fd294eb547b5a044730cfb8a7d5bd7a $ git --git-dir /home/lilydev/vc/lilypond.git/.git/ read-tree 4098351f3fd294eb547b5a044730cfb8a7d5bd7a $ ls $ git --git-dir /home/lilydev/vc/lilypond.git/.git/ checkout-index -a $ ls flower/include/GNUmakefile ls: flower/include/GNUmakefile: No such file or directory $ find -type f | wc -l 1797 $ find ~/vc/gub/downloads/lilypond-HEAD/ -type f | grep -v '\./CVS' | wc -l 2001 $ the CVS repository is available at http://lilypond.org/~hanwen/lilypond.cvsrepo.tar.bz2 -- Han-Wen Nienhuys - [EMAIL PROTECTED] - http://www.xs4all.nl/~hanwen LilyPond Software Design -- Code for Music Notation http://www.lilypond-design.com ___ lilypond-devel mailing list lilypond-devel@gnu.org http://lists.gnu.org/mailman/listinfo/lilypond-devel
Git repository, was Re: doc branching
Hi, On Mon, 23 Oct 2006, Han-Wen Nienhuys wrote: > Interested parties can get the darcs repo at > http://lilypond.org/~hanwen/gub-git/ Well, I cannot. As I stated earlier, I gave up on darcs. > however, I seem to have some trouble with importing the CVS repo into > Git. My attempt is at > > http://lilypond.org/~hanwen/lilypond.git/ Right now getting it. > Unfortunately, it seems to be missing some files. Did I botch up the import, > or is something wrong with git-cvsimport? I found that at least one particular version of git-cvsimport forgot files, but I had the impression that it was because of "--no-rlog". Anyway, I will investigate. (This could take a week or so, as I am travelling.) It might well be a bug in cvsps, or git-cvsimport, or both. Hopefully I can fix it. > the CVS repository is available at > > http://lilypond.org/~hanwen/lilypond.cvsrepo.tar.bz2 I have it. Ciao, Dscho ___ lilypond-devel mailing list lilypond-devel@gnu.org http://lists.gnu.org/mailman/listinfo/lilypond-devel
Re: doc branching
Graham Percival wrote: > > On 8-Apr-06, at 4:01 AM, Cameron Horsburgh wrote: > >> Graham Percival wrote: >> >>> manual, I'll be doing them all at once, so I won't miss anything. I >>> think we still have features introduced in 2.2 that haven't made it into >>> the manual (I'll be calling for a volunteer to do this soon). >> >> I'll have a bit of time over the next week--I'm willing to have a look >> through the last few NEWS files (2.0 on?) and compare them with the >> current (2.9 ?) manual. Any objections? > > Great! Yes, 2.9 is still the most recent manual. > > There's two parts to this job. First, identify which things aren't in > the manual which should be. Second, write the docs for those new > things. :) > > I already know that the following things should be included but aren't: > \killCues > setAboveContext (or something like this) > nested staff delimiters -- > http://lists.gnu.org/archive/html/lilypond-user/2005-11/msg00771.html > > > Cheers, > - Graham > > > Bewdy mate. I'll get a start on the first part and submit a list of what I think needs to be done and where in the manual I think it should go. I hope to do this in the next day or two. Then for part two! I notice that the doc tarball is 2.9.2 but the web page is 2.9.0. Is there any non-trivial difference between the two? Cam ___ lilypond-devel mailing list lilypond-devel@gnu.org http://lists.gnu.org/mailman/listinfo/lilypond-devel
Re: doc branching
On 8-Apr-06, at 4:01 AM, Cameron Horsburgh wrote: Graham Percival wrote: manual, I'll be doing them all at once, so I won't miss anything. I think we still have features introduced in 2.2 that haven't made it into the manual (I'll be calling for a volunteer to do this soon). I'll have a bit of time over the next week--I'm willing to have a look through the last few NEWS files (2.0 on?) and compare them with the current (2.9 ?) manual. Any objections? Great! Yes, 2.9 is still the most recent manual. There's two parts to this job. First, identify which things aren't in the manual which should be. Second, write the docs for those new things. :) I already know that the following things should be included but aren't: \killCues setAboveContext (or something like this) nested staff delimiters -- http://lists.gnu.org/archive/html/lilypond-user/2005-11/msg00771.html Cheers, - Graham ___ lilypond-devel mailing list lilypond-devel@gnu.org http://lists.gnu.org/mailman/listinfo/lilypond-devel
Re: doc branching
Graham Percival wrote: > 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. > I favor this solution. At first glance, it might suggest that new > features won't get documented well, but it should have the opposite > effect: when I _do_ sit down to move new features from NEWS into the > manual, I'll be doing them all at once, so I won't miss anything. I > think we still have features introduced in 2.2 that haven't made it into > the manual (I'll be calling for a volunteer to do this soon). > > Thoughts? > - Graham I'll have a bit of time over the next week--I'm willing to have a look through the last few NEWS files (2.0 on?) and compare them with the current (2.9 ?) manual. Any objections? Cam ___ lilypond-devel mailing list lilypond-devel@gnu.org http://lists.gnu.org/mailman/listinfo/lilypond-devel
Re: doc branching
Hi, On Wed, 5 Apr 2006, Han-Wen Nienhuys wrote: > Pedro Kröger wrote: > > Han-Wen Nienhuys <[EMAIL PROTECTED]> writes: > > > > > Hmmm; part of the problem might also stem from using CVS, which > > > doesn't have good cherry-picking for patches. > > > > would it be a solution to use darcs only for the manual? I know there > > are some ways of syncing darcs and cvs, so maybe the doc stays in cvs > > and Graham has a private darcs repository where he can create branches, > > choose what patches should go where, and so on. > > If we go this route, we could better do it right immediately, and setup a > bzr/darcs/monotone/git/etc. based infrastructure rightaway. I am tracking the current lilypond repository with git. I could donate this git repository (it is ca. 60MB at the moment). I prefer git over the other alternatives: it is blazingly fast, *very* portable (I gave up on porting darcs after a fruitless day), and branching/merging is an easy operation. Ciao, Dscho ___ lilypond-devel mailing list lilypond-devel@gnu.org http://lists.gnu.org/mailman/listinfo/lilypond-devel
Re: doc branching
On 5-Apr-06, at 5:23 AM, Han-Wen Nienhuys wrote: Graham Percival wrote: 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'm in disagreement with Erik over this, as I think that people will want to upgrade their .ly files, instead of upgrading machine generated files which aren't editable. Note that the stream -> .ly conversion is non-existent at present. I'm not certain what "people" will want to do, but I would have loved this a few years ago. I have literally over 50 scores, some dating back to 1.6 days, which I still haven't updated. And I didn't keep pdfs; at the time I assumed that convert-ly would handle everything. Occasionally I have the urge to go back and look at a piece I wrote back then, but this urge is never strong enough to spend half an hour updating that .ly file. Just drop me a line when I should update lilypond.org with the latest doc fixes. 2.9 has everything I'm planning on doing until the weekend. It needs to be backported to 2.8, which I can't do until Thurs evening, so go ahead and move everything from 2.9 Documentation/user/* to 2.8. - Graham ___ lilypond-devel mailing list lilypond-devel@gnu.org http://lists.gnu.org/mailman/listinfo/lilypond-devel
Re: doc branching
Han-Wen Nienhuys wrote: If we go this route, we could better do it right immediately, and setup a bzr/darcs/monotone/git/etc. based infrastructure rightaway. I mean, for the entire lilypond repository. -- Han-Wen Nienhuys - [EMAIL PROTECTED] - http://www.xs4all.nl/~hanwen LilyPond Software Design -- Code for Music Notation http://www.lilypond-design.com ___ lilypond-devel mailing list lilypond-devel@gnu.org http://lists.gnu.org/mailman/listinfo/lilypond-devel
Re: doc branching
Pedro Kröger wrote: Han-Wen Nienhuys <[EMAIL PROTECTED]> writes: Hmmm; part of the problem might also stem from using CVS, which doesn't have good cherry-picking for patches. would it be a solution to use darcs only for the manual? I know there are some ways of syncing darcs and cvs, so maybe the doc stays in cvs and Graham has a private darcs repository where he can create branches, choose what patches should go where, and so on. If we go this route, we could better do it right immediately, and setup a bzr/darcs/monotone/git/etc. based infrastructure rightaway. -- Han-Wen Nienhuys - [EMAIL PROTECTED] - http://www.xs4all.nl/~hanwen LilyPond Software Design -- Code for Music Notation http://www.lilypond-design.com ___ lilypond-devel mailing list lilypond-devel@gnu.org http://lists.gnu.org/mailman/listinfo/lilypond-devel
Re: doc branching
Graham Percival wrote: 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'm in disagreement with Erik over this, as I think that people will want to upgrade their .ly files, instead of upgrading machine generated files which aren't editable. Note that the stream -> .ly conversion is non-existent at present. 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). OK, sounds as if we have decided then :) Just drop me a line when I should update lilypond.org with the latest doc fixes. -- Han-Wen Nienhuys - [EMAIL PROTECTED] - http://www.xs4all.nl/~hanwen LilyPond Software Design -- Code for Music Notation http://www.lilypond-design.com ___ lilypond-devel mailing list lilypond-devel@gnu.org http://lists.gnu.org/mailman/listinfo/lilypond-devel
Re: doc branching
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 ___ lilypond-devel mailing list lilypond-devel@gnu.org http://lists.gnu.org/mailman/listinfo/lilypond-devel
Re: doc branching
Han-Wen Nienhuys <[EMAIL PROTECTED]> writes: > Hmmm; part of the problem might also stem from using CVS, which > doesn't have good cherry-picking for patches. would it be a solution to use darcs only for the manual? I know there are some ways of syncing darcs and cvs, so maybe the doc stays in cvs and Graham has a private darcs repository where he can create branches, choose what patches should go where, and so on. this sort of stuff (mantain 2 different versions) is *very* easy with darcs. Pedro ___ lilypond-devel mailing list lilypond-devel@gnu.org http://lists.gnu.org/mailman/listinfo/lilypond-devel
Re: doc branching
Graham Percival <[EMAIL PROTECTED]> writes: >> 5. Provide a unified documentation and mark features with a version >>number, say, > I suppose that this is possible... but IMO this would completely > clutter the manual with unnecessary info. I think that a compromise would work. Instead of having a big master manual for all versions, we could have only one for the stable version and add devel stuff with a specific tag. (or have devel and stable tags) Pedro ___ lilypond-devel mailing list lilypond-devel@gnu.org http://lists.gnu.org/mailman/listinfo/lilypond-devel
Re: doc branching
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 - [EMAIL PROTECTED] - http://www.xs4all.nl/~hanwen LilyPond Software Design -- Code for Music Notation http://www.lilypond-design.com ___ lilypond-devel mailing list lilypond-devel@gnu.org http://lists.gnu.org/mailman/listinfo/lilypond-devel
Re: doc branching
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 ___ lilypond-devel mailing list lilypond-devel@gnu.org http://lists.gnu.org/mailman/listinfo/lilypond-devel
Re: doc branching
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 - [EMAIL PROTECTED] - http://www.xs4all.nl/~hanwen LilyPond Software Design -- Code for Music Notation http://www.lilypond-design.com ___ lilypond-devel mailing list lilypond-devel@gnu.org http://lists.gnu.org/mailman/listinfo/lilypond-devel
Re: doc branching
On 5-Apr-06, at 12:45 AM, Werner LEMBERG wrote: 5. Provide a unified documentation and mark features with a version number, say, This feature appeared in version 2.7.38. Ideally, such things belong into the margin, but... I suppose that this is possible... but IMO this would completely clutter the manual with unnecessary info. I guess we could remove all feature-version numbers every time we make a .0 stable release... but I'm still not certain that this would be the best option. - Graham ___ lilypond-devel mailing list lilypond-devel@gnu.org http://lists.gnu.org/mailman/listinfo/lilypond-devel
Re: doc branching
> 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. > I favor this solution. At first glance, it might suggest that new > features won't get documented well, but it should have the opposite > effect: when I _do_ sit down to move new features from NEWS into the > manual, I'll be doing them all at once, so I won't miss anything. I > think we still have features introduced in 2.2 that haven't made it > into the manual (I'll be calling for a volunteer to do this soon). 5. Provide a unified documentation and mark features with a version number, say, This feature appeared in version 2.7.38. Ideally, such things belong into the margin, but... Werner ___ lilypond-devel mailing list lilypond-devel@gnu.org http://lists.gnu.org/mailman/listinfo/lilypond-devel
doc branching
Hi all, In the past, there have been periods of half a year (or more) when Mats and I suggest that users should read the development manual instead of the stable manual. Most of the changes I make to the manual apply to the stable branch as well, but due to technical and time considerations, I only make changes to the devel manual. These changes _could_ be backported to the stable manual, but it would be really tiresome to sift through all the differences and determine which parts should be backported and which parts cannot. I see four ways of dealing with this: 1. Status quo. Problem: new users get confused by things I've already fixed in the devel manual. This is frustrating for both them and me -- late in the 2.7 series, there were many questions on -user about issues which I'd clarified in the 2.7 manual, but not in the 2.6 manual. 2. Much shorter devel periods (say, four months). New users still get confused and ask questions about things which I've already clarified, but there's much less fixed material. Problem: this would cause great problems for the programmers, particularly since the next release is 3.0 and we want to change lots of stuff. I'm not seriously proposing this one; I'm just including it here for the sake of completeness. 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. I favor this solution. At first glance, it might suggest that new features won't get documented well, but it should have the opposite effect: when I _do_ sit down to move new features from NEWS into the manual, I'll be doing them all at once, so I won't miss anything. I think we still have features introduced in 2.2 that haven't made it into the manual (I'll be calling for a volunteer to do this soon). This solution also improves the stable documentation -- if the devel and stable docs remain in synch for another few months, the stable docs will be in much better shape when I stop working on them. Just to make sure that I'm totally clear, I'm proposing that new features don't go into Documentation/user/*. They get listed in NEWS, and obviously in input/regression/ and/or input/test/ . Thoughts? - Graham ___ lilypond-devel mailing list lilypond-devel@gnu.org http://lists.gnu.org/mailman/listinfo/lilypond-devel
