doc branching

classic Classic list List threaded Threaded
22 messages Options
12
Reply | Threaded
Open this post in threaded view
|

doc branching

Graham Percival-2
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
[hidden email]
http://lists.gnu.org/mailman/listinfo/lilypond-devel
Reply | Threaded
Open this post in threaded view
|

Re: doc branching

Werner LEMBERG

> 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
[hidden email]
http://lists.gnu.org/mailman/listinfo/lilypond-devel
Reply | Threaded
Open this post in threaded view
|

Re: doc branching

Graham Percival-2

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
[hidden email]
http://lists.gnu.org/mailman/listinfo/lilypond-devel
Reply | Threaded
Open this post in threaded view
|

Re: doc branching

Han-Wen Nienhuys-2
In reply to this post by Graham Percival-2
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 - [hidden email] - http://www.xs4all.nl/~hanwen

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



_______________________________________________
lilypond-devel mailing list
[hidden email]
http://lists.gnu.org/mailman/listinfo/lilypond-devel
Reply | Threaded
Open this post in threaded view
|

Re: doc branching

Graham Percival-2

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
[hidden email]
http://lists.gnu.org/mailman/listinfo/lilypond-devel
Reply | Threaded
Open this post in threaded view
|

Re: doc branching

Han-Wen Nienhuys-2
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 - [hidden email] - http://www.xs4all.nl/~hanwen

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



_______________________________________________
lilypond-devel mailing list
[hidden email]
http://lists.gnu.org/mailman/listinfo/lilypond-devel
Reply | Threaded
Open this post in threaded view
|

Re: doc branching

Pedro Kröger
In reply to this post by Graham Percival-2
Graham Percival <[hidden email]> 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
[hidden email]
http://lists.gnu.org/mailman/listinfo/lilypond-devel
Reply | Threaded
Open this post in threaded view
|

Re: doc branching

Pedro Kröger
In reply to this post by Han-Wen Nienhuys-2
Han-Wen Nienhuys <[hidden email]> 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
[hidden email]
http://lists.gnu.org/mailman/listinfo/lilypond-devel
Reply | Threaded
Open this post in threaded view
|

Re: doc branching

Graham Percival-2
In reply to this post by Han-Wen Nienhuys-2

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
[hidden email]
http://lists.gnu.org/mailman/listinfo/lilypond-devel
Reply | Threaded
Open this post in threaded view
|

Re: doc branching

Han-Wen Nienhuys-2
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 - [hidden email] - http://www.xs4all.nl/~hanwen

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



_______________________________________________
lilypond-devel mailing list
[hidden email]
http://lists.gnu.org/mailman/listinfo/lilypond-devel
Reply | Threaded
Open this post in threaded view
|

Re: doc branching

Han-Wen Nienhuys-2
In reply to this post by Pedro Kröger
Pedro Kröger wrote:
> Han-Wen Nienhuys <[hidden email]> 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 - [hidden email] - http://www.xs4all.nl/~hanwen

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



_______________________________________________
lilypond-devel mailing list
[hidden email]
http://lists.gnu.org/mailman/listinfo/lilypond-devel
Reply | Threaded
Open this post in threaded view
|

Re: doc branching

Han-Wen Nienhuys-2
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 - [hidden email] - http://www.xs4all.nl/~hanwen

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



_______________________________________________
lilypond-devel mailing list
[hidden email]
http://lists.gnu.org/mailman/listinfo/lilypond-devel
Reply | Threaded
Open this post in threaded view
|

Re: doc branching

Graham Percival-2
In reply to this post by Han-Wen Nienhuys-2

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
[hidden email]
http://lists.gnu.org/mailman/listinfo/lilypond-devel
Reply | Threaded
Open this post in threaded view
|

Re: doc branching

Johannes Schindelin
In reply to this post by Han-Wen Nienhuys-2
Hi,

On Wed, 5 Apr 2006, Han-Wen Nienhuys wrote:

> Pedro Kröger wrote:
> > Han-Wen Nienhuys <[hidden email]> 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
[hidden email]
http://lists.gnu.org/mailman/listinfo/lilypond-devel
Reply | Threaded
Open this post in threaded view
|

Re: doc branching

Cameron Horsburgh
In reply to this post by Graham Percival-2
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
[hidden email]
http://lists.gnu.org/mailman/listinfo/lilypond-devel
Reply | Threaded
Open this post in threaded view
|

Re: doc branching

Graham Percival-2

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
[hidden email]
http://lists.gnu.org/mailman/listinfo/lilypond-devel
Reply | Threaded
Open this post in threaded view
|

Re: doc branching

Cameron Horsburgh
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
[hidden email]
http://lists.gnu.org/mailman/listinfo/lilypond-devel
Reply | Threaded
Open this post in threaded view
|

Re: doc branching

Han-Wen Nienhuys-2
In reply to this post by Johannes Schindelin
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 - [hidden email] - http://www.xs4all.nl/~hanwen

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



_______________________________________________
lilypond-devel mailing list
[hidden email]
http://lists.gnu.org/mailman/listinfo/lilypond-devel
Reply | Threaded
Open this post in threaded view
|

Git repository, was Re: doc branching

Johannes Schindelin
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
[hidden email]
http://lists.gnu.org/mailman/listinfo/lilypond-devel
Reply | Threaded
Open this post in threaded view
|

Re: Git repository, was Re: doc branching

Han-Wen Nienhuys-2
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 - [hidden email] - http://www.xs4all.nl/~hanwen

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



_______________________________________________
lilypond-devel mailing list
[hidden email]
http://lists.gnu.org/mailman/listinfo/lilypond-devel
12