Re: GH:zsh-users/zsh-completions.

Re: GH:zsh-users/zsh-completions.

[Julien Nicoulaud]

[-- Attachment #1: Type: text/plain, Size: 9235 bytes --]

Hi Oliver,

Thanks for reaching out to me, those are some valid points and I have been
aware of the issues with this repo for a long time, but could not really
find the time to address it, sorry about that. I added zsh-workers in copy,
I hope you don't mind.

zsh-completions started eight years ago now, with zsh-syntax-highlighting.
Those were just some personal experimentations, but at some points both
started to get a bit a popularity, so I decided to try to make it
"community" projects and moved it to an organization. Both projects
continued evolving from this point and got many contributions, and that is
pretty much it, there is no agenda.

As a side note, I named the organization "zsh-users" and I realized after a
while this was a poor choice, as it sounds too "official". Many users get
confused and think this is part of the zsh project (especially with the git
mirror of the zsh repo). I am open to suggestions regarding this, and if
the zsh team wants me to rename the org, I will do it.

Anyway, a few thoughts about zsh-completions:

   - I believe the release rythm of zsh (~once a year) is a bit too slow
   for completions. We do ~monthly releases, and I think most users importing
   it via a "plugin manager" actually directly use the master branch, which is
   fine IMHO for completions. By the time a compdef lands in a zsh release, it
   can be already obsolete or need bugfixes. I think this is the biggest point
   for having compdefs in a separate repo than the shell itself.
   - I believe a significant part of the contributions we had were because
   the project is hosted on github. It attracts an audience of contributors
   that are not familiar with the "classic way" (mailing list, IRC, patches,
   and different process for a each project), and it makes it very easy for
   "drive-by" contributions and learning by example, which fits well to
   completions. It also easy to review/provide feedback and iterate on patches
   (eg: https://github.com/zsh-users/zsh-completions/pull/512)
   - The initial idea was indeed for zsh-completions to be an "incubator",
   and contribute the compdefs on the mailing-list. The previous point also
   applies to me, it asks me more work to extract a compdef from the repo,
   create a patch against zsh, send it to the mailing list, and follow up. I
   do not spend a lot of time on this project, and I quickly realized that was
   not something I would be able to do on a regular basis, so I did not do it
   at all.
   - If I send a compdef to zsh, what happens then ? We have to wait a
   least for the next release of zsh to delete it from zsh-completions. But
   then, not all distros update to the latest release of zsh, or the compdef
   could have evolved in zsh-completions in the meanwhile, so I can see this
   could be become quite a headache to manage (for users as well).
   - zsh-completions has a lower quality standard than the completions in
   zsh itself. For instance, some compdefs are partial, some compdefs use
   awk/grep/sed/tr instead of the shell builtins, some compdefs use the low
   level API (compadd, etc) instead of the high level one. We often accept it
   as "better than nothing".
   - Some completions are for projects with a very small userbase. Do we
   really want to bloat the zsh repo, and user installations with hundreds of
   compdefs they don't use ?
   - I do not have a strong opinion about licensing. I used this rule
   because we got many pull requests from people just copy-pasting someone
   else's work without any attribution. I think your proposition is good, we
   can use the Zsh license as the default one.
   - My opinion about including completions directly in the upstream
   project is mixed. Either the project already does it, and this is fine. But
   in my experience, when they do not by themselves, contributing a compdef
   often results in endless discussions in bug trackers and poor
   maintainance... IMHO, to write a completion, the knowledge of zsh is more
   important than the knowledge of the command itself, so it feels natural to
   me that completions are written by "zsh experts" rather than "project XXXX
   experts". Another point against completions in upstream project is that it
   makes work a bit harder for packaging (for instance, there is no real clean
   way to handle this in python's setup.py, so each project ends with a more
   or less custom solution).

So the main points are:

   - release cycle different than zsh's one
   - newbie/occasional/one time contributor friendly thanks to:
      - github
      - lower quality standard

Here are some ideas to improve things:

   - Get some core zsh contributors involved in zsh-completions


   - Split completions from the main zsh repo to another one, with:


   1. frequent, regular releases
      2. some clear guidelines for contributing compdefs, and for becoming
      a patch reviewer
      3. github contributing workflow (either by hosting it on github, or
      auto-posting patches from a github mirror, etc)

This idea of having a "zsh-contrib" repo actually applies to more than just
completions: prompts, ZLE widgets, etc.


   - (slightly unrelated) Improve the tooling around completions:


   1. Maybe define some standard metadatas that can be included in
      compdefs, and that can be exploited by other tooling (eg: version of
      program)
      2. I could see your project used to build a permanent
      webapp/dashboard, with the status for each command (does it have a
      completion ? where ? for which version ?).
      3. Work on tooling to lint and unit test completions (eg to invoke a
      compdef programatically, and return matches in an array). I have some
      unpushed stuff I started working on for zsh-completions, to run basic
      checks on pull requests.

I realize that's a lot of points, but I hope it helps moving things forward
:)

Cheers,
Julien

2017-10-14 11:37 GMT+02:00 Oliver Kiddle <okiddle@yahoo.co.uk>:

> I'm one of the people who regularly maintain the completion functions
> distributed with zsh. I've been aware of your function collection on
> github for a while and I think it would be worth giving some thoughts to
> how we can best improve the completion situation for zsh as a whole.
>
> Right at the start of README.md is the assertion that "scripts are meant
> to be contributed to the Zsh project when stable enough". As far as I
> can tell there hasn't been much, or even any, flow of functions to zsh.
>
> I'll start by pointing out something which is perhaps a minor nitpick:
> licensing. You encourage people to include a license which is good but
> if eventual inclusion in zsh is an aim then why not encourage the use
> of the zsh license. Above any arguments about copyleft vs. permissive
> licences, I always prefer to keep things simple by sticking to whatever
> licence a project is currently using. I know Peter has accepted some
> functions with alternate licenses but I'm not fond it. It's also sort
> of ugly having a license at the top of every file. Why not nominate
> the zsh licence as the default license and include a LICENSE file for
> it. Then simply state that where a function deviates from it that it
> should include its own license. If the intention is to include it in the
> upstream project then their license should be preferred.
>
> One of the problems when people contribute a function, either to zsh,
> zsh-users/zsh-completions, or some other project is that they often view
> it as a job done and never bother to come back with improvements or
> fixes. An advantage of keeping them in the author's own github repo is
> that they might be more inclined to maintain it. The disadvantage is
> that it is harder for users to find, especially if there are multiple
> forks. Perhaps something like git submodules or subtree could be used to
> link them in from a master repository?
>
> I've experimented with contributing some functions upstream over the
> past year. Sometimes it works great and the function gets updated by the
> people who know the upstream command best. All too often it gets little
> attention or my pull requests sit ignored. A staging repository such as
> zsh-completions could be good as a temporary home for these.
>
> I'm also concerned about how much feedback people get. Or more
> specifically encouraging a one-time committer to become more involved
> while also improving the quality of each newly submitted function by
> making a few iterations right at the beginning. We've not always done a
> great job on zsh-workers but the people best placed to give feedback are
> there.
>
> Did you create zsh-completions in the first place or did you
> inherit it? If so, why? - as opposed to sending contributions to the
> mailing list.
>
> If you're not aware of it, I'll just mention
>   https://github.com/okapia/zsh-helpoutput
> I had been keeping the output of --help for commands in CVS going back
> years. The idea is to automate detection of changes in upstream
> commands. Things had got fairly bad but I've been trying to get the
> functions included in zsh into better shape.
>
> I'd be interested in any ideas you may have on how we can do things
> better.
>
> Oliver
>

Re: GH:zsh-users/zsh-completions.

[Eric Cook]

On 10/14/2017 10:44 AM, Julien Nicoulaud wrote:

>    - I believe the release rythm of zsh (~once a year) is a bit too slow
>    for completions. We do ~monthly releases, and I think most users importing
>    it via a "plugin manager" actually directly use the master branch, which is
>    fine IMHO for completions. By the time a compdef lands in a zsh release, it
>    can be already obsolete or need bugfixes. I think this is the biggest point
>    for having compdefs in a separate repo than the shell itself.

The release frequency cuts both ways, if the command in question changes frequently,
with the completer keeping in sync and an user continues to use an older version
of the command. they would be presented options that doesn't exist yet. That
would be my biggest point for trying to push those completers into their project's
source tree. While it would awesome if the developers attempt to keep it up to date
there isn't an reason why the original contributor of the completer couldn't help with
that effort too. But once an release of project foo happens and appears on your
os, you have an snapshot of the options supported by that release. bug fixes to the
completer would work like any other bug fix to packages on an os.

Re: GH:zsh-users/zsh-completions.

[Oliver Kiddle]

Firstly, thanks for the detailed reply.

Julien Nicoulaud wrote:
> As a side note, I named the organization "zsh-users" and I realized after a
> while this was a poor choice, as it sounds too "official". Many users get
> confused and think this is part of the zsh project (especially with the git
> mirror of the zsh repo). I am open to suggestions regarding this, and if the
> zsh team wants me to rename the org, I will do it.

I'd leave the name as it is. Renaming now would cause more confusion
than it solves.

>   • I believe the release rythm of zsh (~once a year) is a bit too slow for
>     completions. We do ~monthly releases, and I think most users importing it
>     via a "plugin manager" actually directly use the master branch, which is
>     fine IMHO for completions. By the time a compdef lands in a zsh release, it
>     can be already obsolete or need bugfixes. I think this is the biggest point
>     for having compdefs in a separate repo than the shell itself.

The time it takes for updates to reach a release is not something I
viewed as a problem that needed fixing. It reduces the number of my
silly mistakes that end up in a release. If someone wants, they can take
completion functions from git without upgrading zsh itself - and that's
not especially more effort than pulling in an external collection of
functions.

Ideally, at the time of a zsh release, completion definitions are
up-to-date. So the only descrepancies a user will experience are for
changes between that time and when their distribution released (plus
missing out on new functions). But as Eric pointed out, this cuts both
ways: if you're running something like RHEL or Ubuntu LTS and getting
completions from git you'll have big descrepancies in the opposite
direction.

It is of course Peter's prerogative to determine the zsh release
schedule. If there is general agreement that we want to get completion
changes out faster, we might do that while accomodating the needs of
the rest of the shell by branching for each x.y line and continue more
regular x.y.z releases containing only completion (and perhaps bugfix)
changes. That would also need someone willing to do the associated work
that would impose.

>   • I believe a significant part of the contributions we had were because the
>     project is hosted on github It attracts an audience of contributors that
>     are not familiar with the "classic way" (mailing list, IRC, patches, and
>     different process for a each project), and it makes it very easy for
>     "drive-by" contributions and learning by example, which fits well to
>     completions. It also easy to review/provide feedback and iterate on patches
>     (eg: https://github.com/zsh-users/zsh-completions/pull/512)

I'm sure you're right here.

Does anyone else have views on allowing a github model for completion
functions? Most of my arguments against github usage don't really apply
if we're only talking about completions for commands.

And is there a simple way to provide this without separating the repository?

>   • The initial idea was indeed for zsh-completions to be an "incubator", and
>     contribute the compdefs on the mailing-list. The previous point also
>     applies to me, it asks me more work to extract a compdef from the repo,
>     create a patch against zsh, send it to the mailing list, and follow up. I
>     do not spend a lot of time on this project, and I quickly realized that was
>     not something I would be able to do on a regular basis, so I did not do it
>     at all.

If it's to be an "incubator" going forward, I'm happy to handle the, er, "hatching".

>   • If I send a compdef to zsh, what happens then ? We have to wait a least for
>     the next release of zsh to delete it from zsh-completions. But then, not
>     all distros update to the latest release of zsh, or the compdef could have
>     evolved in zsh-completions in the meanwhile, so I can see this could be
>     become quite a headache to manage (for users as well).

We could alleviate some of those concerns by scheduling "hatching" of functions
for shortly before a zsh release and if zsh-completions does releases shortly
after a zsh release.

>   • zsh-completions has a lower quality standard than the completions in zsh
>     itself. For instance, some compdefs are partial, some compdefs use awk/grep
>     /sed/tr instead of the shell builtins, some compdefs use the low level API
>     (compadd, etc) instead of the high level one. We often accept it as "better
>     than nothing".

There's some overlap in that. There's some pretty decent functions in
zsh-completions and a few in zsh that are not. One or two ought perhaps
to be relegated.

>   • Some completions are for projects with a very small userbase. Do we really
>     want to bloat the zsh repo, and user installations with hundreds of
>     compdefs they don't use ?

I have vague memories of this having come up as a question on the lists
in the past with the conclusion being that we'd be generous in accepting
such functions. They don't tend to be large and it is notable that few
distributions go to the effort of stripping functions intended for other
operating systems. 

A small userbase is perhaps a strong criteria for suggesting that the
function should be contributed upstream....

>   • My opinion about including completions directly in the upstream project is
>     mixed. Either the project already does it, and this is fine. But in my

I agree with these points. Going forward, we should perhaps decide that
on a case-by-case basis.

> So the main points are:

>   • release cycle different than zsh's one
>   • newbie/occasional/one time contributor friendly thanks to:
>       □ github
>       □ lower quality standard

I'd add to that the unclear status of zsh-completions. Is it to be an
incubator, an additional repository for obscure commands, both or the
repository of all completions?

> Here are some ideas to improve things:

>   • Get some core zsh contributors involved in zsh-completions

I'd be happy to help with reviewing new contributions.

>   • Split completions from the main zsh repo to another one, with:

I can't say I'm entirely enthusiastic about this. It was sort-of before
my time but there are good reasons why they were included in the first
place. I'd be interested to hear if anyone else has any views.

We'd have to start worrying about backward compatibility with old releases of
zsh, virtually precluding the use of any new features. Most zsh users want the
completion functions to be there. I really value being able to go to something
like Solaris, RHEL or macOS and the functions are just there even if a tiny bit
dated.

>     This idea of having a "zsh-contrib" repo actually applies to more than just
>     completions: prompts, ZLE widgets, etc.

oh-my-zsh and other projects already occupy that niche.

>   • (slightly unrelated) Improve the tooling around completions:

>      1. Maybe define some standard metadatas that can be included in compdefs,
>         and that can be exploited by other tooling (eg: version of program)

I prefer the metadata to be outside of the functions so that it can be
updated without cluttering the version control for the functions with
non-functional changes. It also allows the metadata to be in one place
even if functions are not all in the same repository.

>      2. I could see your project used to build a permanent webapp/dashboard,
>         with the status for each command (does it have a completion ? where ?
>         for which version ?).

Yes, if someone wants to build on the repository I have in that or some other
way, then that would be great.

>      3. Work on tooling to lint and unit test completions (eg to invoke a
>         compdef programatically, and return matches in an array). I have some
>         unpushed stuff I started working on for zsh-completions, to run basic
>         checks on pull requests.

Some sort of lint tool is a good idea. I'd be inclined to gradually collect
regular expressions into a perl script as I think of them but am open to any
better ideas someone may have on how to do this.

> I realize that's a lot of points, but I hope it helps moving things forward :)

Thanks again for taking the time to think about it and respond.

Oliver

Re: GH:zsh-users/zsh-completions.

[Peter Stephenson]

On Mon, 16 Oct 2017 16:29:52 +0200
Oliver Kiddle <okiddle@yahoo.co.uk> wrote:
> Does anyone else have views on allowing a github model for completion
> functions? Most of my arguments against github usage don't really apply
> if we're only talking about completions for commands.

It's already allowed --- anyone can set this up, and they already have.
Anyone can use any set of shell functions they like.

The next question is more about how it interacts with the source
distribution.  If it overrides it --- which is easy to set up, too ---
there's no actual clash.  The question then becomes more one of bundling
and installation.

If it completely replaces it, that's probably not a problem since
developers can easily get the completions from elsewhere, and again it
becomes a bundling problem for distribution.  It's not clear to me how
helpful that is in practice.  If you have a stable branch in the original
repository, it's going to have to be maintained as an update from the
development branch for each completion separately --- which isn't much
different from just copying it over to the source distribution, where
the update also gets a bit more visibility from people not necessarily
interested in a rapidly changing completion repository.

> And is there a simple way to provide this without separating the repository?

That seems to me the wrong way to go.  There's no absolute need for
completions to be in the same place as the source.  Either keep them
separate and updated and installed separately (but potentially bundled
with a source release for convenience) or keep them (or an stabilised
version, as above) with the source, with the restrictions that implies.

pws

Re: GH:zsh-users/zsh-completions.

[Bart Schaefer]

On Mon, Oct 16, 2017 at 8:11 AM, Peter Stephenson
<p.stephenson@samsung.com> wrote:
>
> That seems to me the wrong way to go.  There's no absolute need for
> completions to be in the same place as the source.  Either keep them
> separate and updated and installed separately (but potentially bundled
> with a source release for convenience) or keep them (or an stabilised
> version, as above) with the source, with the restrictions that implies.


The main issues for me would be (1) where are bugs reported and
solutions discussed, and (2) at how many different places (github,
sourceforge, etc.) must I maintain accounts (and corresponding
separate git clones) in order to be able to contribute?

Re: GH:zsh-users/zsh-completions.

[gi1242+zsh]

On Mon, Oct 16, 2017 at 04:29:52PM +0200, Oliver Kiddle wrote:

>> I believe a significant part of the contributions we had were because the
>> project is hosted on github It attracts an audience of contributors that
>> are not familiar with the "classic way" (mailing list, IRC, patches, and
>> different process for a each project), and it makes it very easy for
>> "drive-by" contributions and learning by example, which fits well to
>> completions. It also easy to review/provide feedback and iterate on
>> patches (eg: https://github.com/zsh-users/zsh-completions/pull/512)
> 
> I'm sure you're right here.
> 
> Does anyone else have views on allowing a github model for completion
> functions? Most of my arguments against github usage don't really
> apply if we're only talking about completions for commands.

My $0.02, since I contributed a completion script recently: I didn't
find clear instructions on contributing on the main web page. I went to
the tracker, and saw a note there. Then I didn't know if I could post to
the list without being subscribed, so I subscribed. Confirmed. And then
I submitted.

That's a lot of steps, and perhaps not everyone will do this.

Perhaps you could have a direct note on the main webpage on your
preferred contribution mechanism? Also allow people to contribute
without subscribing. (Hopefully in a way that doesn't get you insane
amounts of spam.)

Finally, if you're considering the new forking model for people
submitting patches, can I suggest GitLab

    https://about.gitlab.com/

as an alternative to GitHub. Its feature set is comparable to GitHub,
and is completely open source.

GI

PS: Looking through your git logs looks like I sent you a bunch of
    completions in 2011/12. And then nothing until recently. I'll check
    if to see if I have any more local completion improvements that
    might be useful and send them along.

-- 
Marketer to coder: "You start coding. I'll go find out what they want."

Re: GH:zsh-users/zsh-completions.

[Peter Stephenson]

On Mon, 16 Oct 2017 08:24:36 -0700
Bart Schaefer <schaefer@brasslantern.com> wrote:
> On Mon, Oct 16, 2017 at 8:11 AM, Peter Stephenson
> <p.stephenson@samsung.com> wrote:
> >
> > That seems to me the wrong way to go.  There's no absolute need for
> > completions to be in the same place as the source.  Either keep them
> > separate and updated and installed separately (but potentially bundled
> > with a source release for convenience) or keep them (or an stabilised
> > version, as above) with the source, with the restrictions that implies.
>
> The main issues for me would be (1) where are bugs reported and
> solutions discussed,

If we expected lots more activity in the completion area, it might be
worth thinking about another mailing list regardless of where the
repository is.  Presumably there would be requests to cherry-pick
people's changes that needed to go somewhere.

The disadvantage is this has overlap with the users list (is this
a shell feature or just an issue with a completion script?) and
history suggests the human race isn't very good at dealing with
overlapping mailing lists.

> and (2) at how many different places (github,
> sourceforge, etc.) must I maintain accounts (and corresponding
> separate git clones) in order to be able to contribute?

It's easy to have additional repositories at Sourceforge --- the
question is whether they can be set up conveniently for the desired
model, which I don't know.  I think in any case this is easier than
trying to mix and match with a single repsository in Sourceforge --- the
expense being you'd clone one extra repo but identically to how you do
the source repository.  That's already how the website repository works.
But that might not get us what's required to get this off the ground.

pws

Re: GH:zsh-users/zsh-completions.

[gi1242+zsh]

On Mon, Oct 16, 2017 at 04:42:39PM +0100, Peter Stephenson wrote:

> It's easy to have additional repositories at Sourceforge --- the
> question is whether they can be set up conveniently for the desired
> model, which I don't know.

If this is the path you are choosing, then take a look at "git
subtrees". With this someone can simply clone the "whole source" and
make changes anywhere (including completions), without even knowing
there is a separate completion repository. Alternately someone can clone
just the completions directory and only make change there.

One of the devs would have to periodically do a

    git subtree pull / push

to incorporate changes to/from the completion directory to the whole
source.

I use git subtrees all the time and am constantly annoyed by the
fact that the zsh git completion doesn't know about subtrees on my
system. But maybe that will change shortly ... :)

GI

-- 
'MCSE' -- Minesweeper Consultant & Solitaire Expert

Re: GH:zsh-users/zsh-completions.

[Daniel Shahaf]

Peter Stephenson wrote on Mon, 16 Oct 2017 16:11 +0100:
> That seems to me the wrong way to go.  There's no absolute need for
> completions to be in the same place as the source.

I think, in the long term, completions should be generated by option
parsing libraries (getopt(3), optparse, GetOpt::Long, etc).  The way I
see it is:

- Option parsing libraries compile the --options specification --- which
  they already have --- into a format usable by the shells.  That format
  is an API exposed by the shells.

- That format could be either "autoloadable functions to be run by
  compsys" or possibly a shell-agnostic format, that bash and zsh both
  know how to parse.

- The information could be made available to the shells either as a static
  file at a well-known path (compare /usr/share/pkg-config/foo-1.pc) or
  as the dynamic output of a standardly-named "foo --parseable-help"
  flag.  The former has the advantage that it's automatically
  detectable; the latter would require <handwave/> for the shells to
  know that a particular command supports that flag.  (to avoid the
  "`hostname --help` on solaris" thing)

Then completions would be automatically up to date, but on the flip side
it'd be harder to implement a sweeping change across all completions in
the world: we'd have to collaborate with the various option parsing
libraries on getting new compsys features exercised.  (And with bash
too, if the interchange format is shell-agnostic)

That's my blue sky.  It won't eliminate all code in Completions/ ---
functions such as _git would still have a reason to exist --- but it'd
eliminate the tedious work of copying --help output, downcasing the
first letter of every line, and doing that again after a new release of
the program being completed.

Sorry for the brain dump.

Daniel

Re: GH:zsh-users/zsh-completions.

[Bart Schaefer]

On Mon, Oct 16, 2017 at 8:42 AM, Peter Stephenson
<p.stephenson@samsung.com> wrote:
>
> It's easy to have additional repositories at Sourceforge --- the
> question is whether they can be set up conveniently for the desired
> model, which I don't know.

An additional thing that occurs to me as I run "make" is that the
ZSH_PATCHLEVEL variable is derived from the latest git commit hash,
which currently at least includes changes to functions and completions
etc.  Perhaps the subtree approach suggested by GI would resolve that.

Re: GH:zsh-users/zsh-completions.

[Oliver Kiddle]

Peter wrote:
> The next question is more about how it interacts with the source
> distribution.  If it overrides it --- which is easy to set up, too ---
> there's no actual clash.  The question then becomes more one of bundling
> and installation.

Having it override it makes sense, though we would be reliant on people
doing the packaging to get that right. It might mean that the functions get
installed with a flattened directory structure. And some distributions
may take exception to the duplication of functions resulting in users
having to install both zsh and zsh-completions before compinit works.

There's also the question of what we do about Base/* Zsh/* comp* and the
some more borderline things like Unix/Type/_files, Unix/Type/(anything
else called from Zsh/*), bashcompinit etc. We'd also need to think about
the contents of compsys.yo.

> > And is there a simple way to provide this without separating the repository?
>
> That seems to me the wrong way to go.  There's no absolute need for
> completions to be in the same place as the source.  Either keep them
> separate and updated and installed separately (but potentially bundled
> with a source release for convenience) or keep them (or an stabilised
> version, as above) with the source, with the restrictions that implies.

I wasn't expecting this reaction.

I guess that if zsh releases continue to include the functions (or
at least the stable/decent quality subset) then that would allay the
concerns I have with such as separation.

The main disadvantage would be having to think about backward
compatibility with older zsh releases.

> If we expected lots more activity in the completion area, it might be
> worth thinking about another mailing list regardless of where the
> repository is.  Presumably there would be requests to cherry-pick
> people's changes that needed to go somewhere.

Perhaps, though I imagined pull requests being the main avenue for
cherry-pick requests. A mailing list can have value for more general
discussion and if someone prefers to send patches to a list then we can
easily accomodate that too.

> The disadvantage is this has overlap with the users list (is this

I don't think that would be too much of a problem.

> > and (2) at how many different places (github,
> > sourceforge, etc.) must I maintain accounts (and corresponding
> > separate git clones) in order to be able to contribute?

> It's easy to have additional repositories at Sourceforge --- the
> question is whether they can be set up conveniently for the desired
> model, which I don't know.  I think in any case this is easier than

I suspect that using Sourceforge would sort of miss half the point.
Sourceforge does support forks and "merge" requests but the idea is to
make it easier for casual contributors and these days that means github.
Maybe gitlab would be fine too.

Oliver

PS. My comment about oh-my-zsh in my previous mail might have sounded
dismissive but if the model proves a success, we might farm out the
promptinit, zle stuff in a similar manner. There isn't much activity in
terms of accepting pull requests at oh-my-zsh these days which is
something of a concern even if I have no interest in using it myself. No
shortage of pull requests however.

Re: GH:zsh-users/zsh-completions.

[Peter Stephenson]

On Tue, 17 Oct 2017 09:53:45 +0200
Oliver Kiddle <okiddle@yahoo.co.uk> wrote:
> Having it override it makes sense, though we would be reliant on people
> doing the packaging to get that right. It might mean that the functions get
> installed with a flattened directory structure. And some distributions
> may take exception to the duplication of functions resulting in users
> having to install both zsh and zsh-completions before compinit works.

Yes, duplication and incompatibility needs some thinking about.  But if
the source bundle is distributing a completion bundle in an identical
format to (but possibly rather different contents from) the more chaotic
completion set, it should be possible to arrange to pick one
or the other complete, and there's no absolute need to supply the
rapidly varying one at all in a distribution.  In fact, in some ways it
seems a bit pointless to make a package out of it --- it could just come
as a mechanism for keeping it updated.

> I suspect that using Sourceforge would sort of miss half the point.
> Sourceforge does support forks and "merge" requests but the idea is to
> make it easier for casual contributors and these days that means github.
> Maybe gitlab would be fine too.

That's what I kind of imagined.  But it would still be possible to do
subrepositories, wouldn't it?  The source could be set up by default to
pull as an anonymous user from git??b, which should work for anyone
setting up git (up to subtleties like needing to use http instead off
ssh to get through a proxy), with instructions about how to update if
you are going to change things.  That would reduce the problems Bart
noted.

pws

Re: GH:zsh-users/zsh-completions.

[Oliver Kiddle]

gi1242+zsh@gmail.com wrote:
> Perhaps you could have a direct note on the main webpage on your
> preferred contribution mechanism? Also allow people to contribute
> without subscribing. (Hopefully in a way that doesn't get you insane
> amounts of spam.)

I've added a note to the web pages (in Arc/git.html) on how to
contribute. I'm fairly sure you don't need to be subscribed to post to
the lists.

The web pages are another area where volunteers to help improve things
would be much appreciated. The basic design of them dates back to the
90s. I seem to remember the wizard picture used to look quite large
whereas it isn't much more than an icon now.

Oliver

Re: GH:zsh-users/zsh-completions.

[Joey Pabalinas]

[-- Attachment #1: Type: text/plain, Size: 2647 bytes --]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA256

On October 16, 2017 5:49PM UTC, GI <gi1242+zsh@gmail.com> wrote:

> > It's easy to have additional repositories at Sourceforge --- the
> > question is whether they can be set up conveniently for the desired
> > model, which I don"t know.
>
> If this is the path you are choosing, then take a look at "git
> subtrees". With this someone can simply clone the "whole source" and
> make changes anywhere (including completions), without even knowing
> there is a separate completion repository.

Although subtrees have their uses, in my opinion, uses them would result in
nearly the same issues as we are currently having.

Git subtrees lend themselves better when developing both main project
and sub-project within the same directory (a "system approach"). This, however,
would be more akin to a "vendor branch": a branch which allows you to access
a well-defined version of a vendor external component or VCS subdirectory, and
which is only updated with the new version of every release of that external
component. I often hear this referred to as a "component-approach", where the
*all* system is viewed as a collection of separate components developed on
their own.

In this case, we have a project and a sub-project with their own respective
lifecycles; neither of which are developed at the same rhythm, tagged together
at the same time, nor even tagged with the same name.

I feel like a good compromise would be for there to be a seperate, isolated
`zsh-completions` repository that both projects can submodule; this would
slightly relieve the pressures of trying to keep development rhythms in
sync, and will, in my opinion, make it simpler, not to mention much less
painful, to share changes between the two projects.

Joey Pabalinas
<alyptik@protonmail.com>
-----BEGIN PGP SIGNATURE-----

iQIzBAEBCAAdFiEEKlZXrihdNOcUPZTNruvLfWhyVBkFAlnmcZIACgkQruvLfWhy
VBk4rBAApPxP237mOtl1G4K9UZN9pV1jXVsA6vsHzUvUWlehviF/9yM4cWRVQzBR
wWSEqMzL15M4chhzN+cy7pO54mijdV7lb5kQhOE58unBCNHFK9jwrv+wukGuZwoq
13568HTG67yp9q/BOoKACDZYs4wtkHMotTAOEJJaabmZFMPR5+o0VOq8mosovvdQ
SA6ER6PViNRpj5O7no/j/bEIT4hi5v/xjw4+9u4XVh3zM8IdeadsbBGQErYeoMF0
JaHYYHtEyKuPeXFI697iPu+1EMyrKfSMXDxQxupLtF9eIz4vdToRsXsmbOkVCFpR
q6Jg/w6+QxOVkWB0MgjNmv0oSY1nIULLNR/Brw1bCzuA7/WMo/aziE8iGRUjaWAX
W7dJR2qkDS7qvtmOu/60ttAKTXG0gY9An3I+h5UIiMK7T53OghbGzp1OP1WTb4H8
GWgqFVn2ZRc9s5Z68YJ6VrIY2fMcwAgwpbpXjWQKTnNY1k0rDXbilSKbkBP/Sks2
KLcf+uXKJsyyYxN+ViPqymjxidPYLn9iMmm7r9W8M1lN8H2E4FfsD2JFEcapKw3k
lkdlu7kXCQr6rcY8rla/GEQOOOp7LnuMJEKmgzMFtk50CaCFDyKIkJeBevvF7JHf
zt/zgCIT4PQ8wojXmRA/08NoItD9vG84NQc8s2jt8Gs3csFvyzg=
=nZYX
-----END PGP SIGNATURE-----

Re: GH:zsh-users/zsh-completions.

[Oliver Kiddle]

Joey Pabalinas wrote:
> Git subtrees lend themselves better when developing both main project
> and sub-project within the same directory (a "system approach"). This, however,
> would be more akin to a "vendor branch": a branch which allows you to access

Thanks, having not used submodules and subtrees before I was
experimenting to see how they might be used and this has helped clarify
things.

I also concluded that we can't easily pull in a subdirectory of the
existing zsh-completions project: it is all or nothing. Maybe it is
somehow possible with a subtree merge (a different thing from git
subtree) but my attempts at that failed. However:

> I feel like a good compromise would be for there to be a seperate, isolated
> `zsh-completions` repository that both projects can submodule;

That might work. Not sure I like there then being three projects (plus
upstreams). The whole idea is to make it less confusing for someone
wanting to contribute. Maybe the "incubator" completions could be pulled
in to the zsh repository with the others but excluded from a zsh release
tarball. Or we could use a separate orphan git branch.

If we're to separate completions out of zsh, there's also the question
of how much to separate out. Different levels would be:
  * Separate away all of it, even including Base and compinit
  * Leave back only the core
  * Also leave completion of Zsh builtins
  * Also leave any functions that are called from these, i.e. a good chunk
    of Unix/Type, especially _files; separating just external commands
  * Start with an empty new repository leaving all the existing stuff

Unless we use the empty new repository, actually making the separation
is quite a bit of work given Makefile stuff aswell. And as mentioned
before, separating also creates the problem of needing to worry about
backward compatibility in functions.

What I would prefer is for us to leave zsh completions where they are but
optimise the workflow:

  * Encourage completion contributions in the form of github pull
    requests to the zsh-users/zsh mirror. This isn't hard to handle:
    add github as an additional remote, fetch refs/remotes/xxxx/pr/*,
    cherry-pick and push to the sourceforge master.
  * Require no mailing list message for basic completion updates.
  * Rethink the need to update ChangeLog on every commit.

We preserved the ChangeLog in its existing form when migrating from CVS
largely so that we were changing as little as possible. But we have git
log. All new ChangeLog entries can be autogenerated as a whole as part
of rolling a release for inclusion in the tarball. Even for the tarball
I'd argue that most users would prefer a well produced NEWS file update
to the detailed ChangeLog.

I realise that this doesn't solve the problems with how to hatch
completions from zsh-completions.

Oliver

Re: GH:zsh-users/zsh-completions.

[Bart Schaefer]

On Oct 18,  6:23pm, Oliver Kiddle wrote:
}
} We preserved the ChangeLog in its existing form when migrating from CVS
} largely so that we were changing as little as possible. But we have git
} log. All new ChangeLog entries can be autogenerated

This is so appealing in theory and yet so horrible (IMO) in practice.
Git log format does not lend itself to this [*] and its immutability
makes it impossible to correct errors (of which we have plenty) or to
fix mis-attribution when e.g. one of the developers is committing on
behalf of some other contributor who should get credit.


[*] Yes, I know you can use formats to present the log in a whole lot
of flexible ways.  But the one thing you can't change is what info is
stored by git in the first place, to which to apply those formats.

-- 
Barton E. Schaefer

Re: GH:zsh-users/zsh-completions.

[Joey Pabalinas]

[-- Attachment #1: Type: text/plain, Size: 1520 bytes --]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA256

Oliver Kiddle wrote:
> That might work. Not sure I like there then being three projects (plus
> upstreams). The whole idea is to make it less confusing for someone
> wanting to contribute. Maybe the "incubator" completions could be pulled
> in to the zsh repository with the others but excluded from a zsh release
> tarball. Or we could use a separate orphan git branch.

Yeah, I mean no matter what is decided on, there is bound to be at least a
little bit of messiness involved. I do sort of like that "incubator" idea,
though; I don't really see any obvious problems with that sort of approach.

Joey Pabalinas
<alyptik@protonmail.com>
-----BEGIN PGP SIGNATURE-----

iQIzBAEBCAAdFiEEKlZXrihdNOcUPZTNruvLfWhyVBkFAlnoACQACgkQruvLfWhy
VBkuvQ/7B3Q77zCH9syBqYZUlAWMaCgrz7/flxobxVviVG8D93TUAE5JlHz7+qdo
zud0jjUIvLPaHoYQLlQbwkuThgemR4MbcTcYA/hUl+9WDt9QQi1Oie4bKl0DI+Ll
puoCnXdzAv934MmyxGRqWFvYa8sgOrQQ+EZIKY8MGt+MwXSku/6gCCyuLqHoxQcJ
hYaLbdipTmGrMWI4GCkQP5/NUP8bLXs827w+l5Rx1x16CrqVIRv7MhHdCf4+xv53
7tP6NYFYBXASjKekbhOHTJL007nqFiqT+HOafUIoRYqYQZ0ibktQ/q/DsLa2s8bR
alEMAfdkH669e02UML0ZLuzcnRoLZKNYwWNH41Ef524HxWPrwdskqa0MXZUYX9Ok
8I0VUqizoKy0sTNesf6S+8zyno3adEgAHeTXmwNs8Cx7n00rd7z//N7nIes2LeuU
gkKSPZs3HAACkWrF9EgiAbWU8IykIZzMl83xI3fKZq7KURBvZT04tPap6iX1x8rd
0AHTHODAGjum+RtjHkZtJxYE35JuYX2ytLBD25eumN6cpHWqEK8lXTu8QuNxerr8
h3/pp506emlplNDzVsvs79bXMZrfuR2ivlh9Le4f+Vl11ABHdAiwnYKqnYfnE4mM
QEt5w5qTIgJYJyr2Cx9X119BDwztOmTtlkKGu7BKJ5fNhmR3PCQ=
=uBhQ
-----END PGP SIGNATURE-----

Re: GH:zsh-users/zsh-completions.

[Aaron Schrab]

At 18:09 -0700 18 Oct 2017, Bart Schaefer <schaefer@brasslantern.com> wrote:
>[*] Yes, I know you can use formats to present the log in a whole lot
>of flexible ways.  But the one thing you can't change is what info is
>stored by git in the first place, to which to apply those formats.

That's not completely true. There is git-replace(1) which can be used to 
create replacement versions of objects, in this case commits.  The 
references generated by that aren't propagated between repositories by 
default, but it isn't difficult to change the configuration of a 
repository to have those included with push and/or fetch. Once those 
references are in the expected place, they will be used by default for 
most git commands.

Re: GH:zsh-users/zsh-completions.

[Bart Schaefer]

On Oct 19, 12:03am, Aaron Schrab wrote:
} Subject: Re: GH:zsh-users/zsh-completions.
}
} At 18:09 -0700 18 Oct 2017, Bart Schaefer <schaefer@brasslantern.com> wrote:
} >[*] Yes, I know you can use formats to present the log in a whole lot
} >of flexible ways.  But the one thing you can't change is what info is
} >stored by git in the first place, to which to apply those formats.
} 
} That's not completely true. There is git-replace(1) which can be used to 
} create replacement versions of objects, in this case commits.

Apologies; the reason I put that in a footnote is because when I say
"can't change what info is stored" I didn't mean "can't replace the
data" I meant "can't alter the data structures" (or "schema" if you
prefer to treat it like a database).  I wasn't referring back to the
"immutable" log messages.

Just as a trivial but not entirely irrelevant example, we can't make
git distinguish a zsh mailing list article sequence number and output
it in a particular way in the autogenerated commit log by changing
the format string.

Re: GH:zsh-users/zsh-completions.

[Daniel Shahaf]

[having trouble following everything in this thread; replying to just
one section]

Oliver Kiddle wrote on Wed, Oct 18, 2017 at 18:23:22 +0200:
> What I would prefer is for us to leave zsh completions where they are but
> optimise the workflow:
> 
>   * Encourage completion contributions in the form of github pull
>     requests to the zsh-users/zsh mirror. This isn't hard to handle:
>     add github as an additional remote, fetch refs/remotes/xxxx/pr/*,
>     cherry-pick and push to the sourceforge master.

Note that this is already happening: people sometimes submit pull
requests to zsh-users/zsh.  Some of us are subscribed to notifications
from that repository and handle such pull requests, either by fetching
them from github and pushing them to sourceforge as Oliver describes, or
by redirecting them to -workers@ for discussion and review.

Moreover, we could just as easily have both a github mirror and a gitlab
mirror and accept pull requests on both of them; all we need is some
maintainers (or this list) to subscribe to pull request notifications
from the gitlab mirror, and then to fetch pull requests from gitlab and
push them to sourceforge in the same manner as done for github.

>   * Require no mailing list message for basic completion updates.
>   * Rethink the need to update ChangeLog on every commit.

I think this is a subtly different issue, isn't it?  The "post to
-workers@" and "update ChangeLog" steps are only visible to the core
maintainer who integrates a change; they are not visible to the
contributor of the patch or to the end-users who consume it.

Cheers,

Daniel

> I realise that this doesn't solve the problems with how to hatch
> completions from zsh-completions.

Re: GH:zsh-users/zsh-completions.

[Daniel Tameling]

Oliver Kiddle <okiddle@yahoo.co.uk> writes:

> The web pages are another area where volunteers to help improve things
> would be much appreciated. The basic design of them dates back to the
> 90s. I seem to remember the wizard picture used to look quite large
> whereas it isn't much more than an icon now.
>

I had a quick look at the web page, and it seems it suffers from link
rot.

Here are a few things I found:

- Under "useful links" the Linux Magazine articles are gone.

- Under "about these pages" the "World Wide Web" link is dead, and the
  "Kevin Sullivan" and "Oliver Kiddle" links don't forward to something
  meaningful.

- The systems listed under http://zsh.sourceforge.net/Etc/machines.html
  look quite old to me.

- Some of the mirrors listed at http://zsh.sourceforge.net/FAQ/META.html
  seem to be gone.

Best regards,
Daniel

Re: GH:zsh-users/zsh-completions.

[Oliver Kiddle]

On 19 Oct, Daniel Shahaf wrote:
> [having trouble following everything in this thread; replying to just
> one section]

Sorry. I suspect you weren't alone. We didn't really come to any useful
conclusion so I'll try to distill it down to the key alternatives. Note
that this is no longer about the external zsh-completions project.

1) A suggestion was made to separate the completion functions out into a
separate project but continuing to include the functions in zsh releases
and the zsh git repository via git submodule.

   This strikes me as being a bit extreme. As a separate project it
   would need to take care of backward compatibility. It could lead to
   them not being available on some systems due to separate packaging.
   And setting it all up would be a chunk of work. But there are
   advantages: less noise on zsh-workers, more frequent releases for
   completions, easier and less intimidating for casual contributors.

2) Keep things together but encourage completion contributions in the
form of pull requests on github and gitlab mirrors. Along with this, I'd
also suggest that we drop the requirement for a mailing list message for
basic completion updates.

   This gets some of the advantages.

3) Do nothing.

It'd be good to know which of these options has broad support before
getting bogged down on the details.

Oliver

Re: GH:zsh-users/zsh-completions.

[Daniel Shahaf]

Oliver Kiddle wrote on Tue, 31 Oct 2017 00:38 +0100:
> On 19 Oct, Daniel Shahaf wrote:
> > [having trouble following everything in this thread; replying to just
> > one section]
> 
> Sorry. I suspect you weren't alone. We didn't really come to any useful
> conclusion so I'll try to distill it down to the key alternatives. Note
> that this is no longer about the external zsh-completions project.
> 

Thanks for summarising.

> 1) A suggestion was made to separate the completion functions out into a
> separate project but continuing to include the functions in zsh releases
> and the zsh git repository via git submodule.
> 
>    This strikes me as being a bit extreme. As a separate project it
>    would need to take care of backward compatibility. It could lead to
>    them not being available on some systems due to separate packaging.
>    And setting it all up would be a chunk of work. But there are
>    advantages: less noise on zsh-workers, more frequent releases for
>    completions, easier and less intimidating for casual contributors.
> 

Let's enumerate the advantages and see if there are other ways to
achieve them.  (As you have done.)

> 2) Keep things together but encourage completion contributions in the
> form of pull requests on github and gitlab mirrors. Along with this, I'd
> also suggest that we drop the requirement for a mailing list message for
> basic completion updates.
> 
>    This gets some of the advantages.
> 

I don't see a problem with encouraging patch submission via git??b or
any other channel, provided that (a) we are responsive over the channels
we advertise as 'official', (b) we don't split brain the discussions; i.e.,
we continue to have just one forum for discussing patches that need
discussion (because they're controversial or invasive or ...).  I assume that
forum would continue to be zsh-workers@.

I'd be happy to consider a different workflow for commits.  The
requirement to first post your own patch and then copy the X-Seq header
before pushing it just adds work to maintainers for little benefit.  (We
can continue to add X-Seq references when they're informative to the
commit or changelog message, of course.)

Note, I'd still love for there to be a mailing list that all commits'
diffs are emailed to --- diffs, not just notifications --- but that list
needn't be -workers@; it could be a separate list (say, zsh-commits@).

The remaining point is more frequent releases for completion.  This
again brings compatibility questions, e.g., when we introduced the
typeset reserved word syntax, the completion in master wouldn't have
been usable by released  zsh's; so we need some way to distinguish
Completions/ changes that are for master only from those that are
suitable for released versions too.  I guess that boils down to maintaining
a git branch of the latest release that contains relevant Completions/
commits?  This would require maintainers to commit every patch twice,
though.

> 3) Do nothing.
> 
> It'd be good to know which of these options has broad support before
> getting bogged down on the details.
> 
> Oliver

Re: GH:zsh-users/zsh-completions.

[Oliver Kiddle]

Daniel Shahaf wrote:
> > 1) A suggestion was made to separate the completion functions out into a
> > separate project but continuing to include the functions in zsh releases
> > and the zsh git repository via git submodule.

> Let's enumerate the advantages and see if there are other ways to
> achieve them.  (As you have done.)

A further advantage relates to the following point that Julien raised:

| | • If I send a compdef to zsh, what happens then ? We have to wait a least for
| |   the next release of zsh to delete it from zsh-completions. But then, not
| |   all distros update to the latest release of zsh, or the compdef could have
| |   evolved in zsh-completions in the meanwhile, so I can see this could be
| |   become quite a headache to manage (for users as well).

Perhaps zsh-completions could add a separate directory containing
functions that graduated to zsh. Copies of other functions that are
newish in zsh might also go there, perhaps in backported form. Packagers
would need to arrange for this to come at the end of $fpath which
might be a little tricky.

> I don't see a problem with encouraging patch submission via git??b or
> any other channel, provided that (a) we are responsive over the channels
> we advertise as 'official', (b) we don't split brain the discussions; i.e.,
> we continue to have just one forum for discussing patches that need
> discussion (because they're controversial or invasive or ...).  I assume that
> forum would continue to be zsh-workers@.

Yes, that's how I would envisage it.

> I'd be happy to consider a different workflow for commits.  The
> requirement to first post your own patch and then copy the X-Seq header
> before pushing it just adds work to maintainers for little benefit.  (We
> can continue to add X-Seq references when they're informative to the
> commit or changelog message, of course.)

> Note, I'd still love for there to be a mailing list that all commits'
> diffs are emailed to --- diffs, not just notifications --- but that list
> needn't be -workers@; it could be a separate list (say, zsh-commits@).

If that removes the need to manually post patches for basic completion
updates I'd be in favour of that. An option might be to have that only
take commits that don't have an X-Seq reference in the commit message.

> The remaining point is more frequent releases for completion.  This
> again brings compatibility questions, e.g., when we introduced the
> typeset reserved word syntax, the completion in master wouldn't have
> been usable by released  zsh's; so we need some way to distinguish
> Completions/ changes that are for master only from those that are
> suitable for released versions too.  I guess that boils down to maintaining
> a git branch of the latest release that contains relevant Completions/
> commits?  This would require maintainers to commit every patch twice,
> though.

I'd be happy enough to commit twice. We did that in the past with
3.0, 4.0 and 4.2 branches. But that approach also requires us to make
releases of the branch. I alluded to something along these lines in
41908 ¶4.

Backporting to the most recent release branch is rarely a big deal.
Certainly compared to what a separate project might find users.
expecting (RHEL 6 is in wide use still and has 4.3.11).

Oliver

ChangeLogs (Re: GH:zsh-users/zsh-completions.)

[Oliver Kiddle]

On 18 Oct, Bart wrote:
> }
> } We preserved the ChangeLog in its existing form when migrating from CVS
> } largely so that we were changing as little as possible. But we have git
> } log. All new ChangeLog entries can be autogenerated
>
> This is so appealing in theory and yet so horrible (IMO) in practice.
> Git log format does not lend itself to this [*] and its immutability
> makes it impossible to correct errors (of which we have plenty) or to
> fix mis-attribution when e.g. one of the developers is committing on
> behalf of some other contributor who should get credit.

We've already got the situation that git logs can't be retrospectively
corrected. If the value of a ChangeLog lies in its mutability that
doesn't necessarily have to be lost if we auto-generate a ChangeLog
before a release. As Aaron mentoned we could push replacement
references. We might also use git notes for things like mailing list
cross-references. So provided whoever makes the release is pulling
replacement refs, the ChangeLog should go out corrected. And added to
that we'd at least have a clear if clumsy mechanism for corrections to
git logs.

I held off replying earlier because I didn't want the main thread to get
side-tracked on what isn't necessarily the most important suggestion
there.

Oliver

Re: ChangeLogs (Re: GH:zsh-users/zsh-completions.)

[Bart Schaefer]

On Wed, Nov 1, 2017 at 4:33 PM, Oliver Kiddle <okiddle@yahoo.co.uk> wrote:
>
> We've already got the situation that git logs can't be retrospectively
> corrected. If the value of a ChangeLog lies in its mutability that
> doesn't necessarily have to be lost if we auto-generate a ChangeLog
> before a release.

It would actually be OK with me to stop maintaining a monolithic
ChangeLog.  It would be more useful to generate a "release notes" file
that has only the changes since the last such file.  That would allow
manual corrections to said file to be preserved without concern that
they'd be stepped on by the next auto-generate, and make it a lot
easier to see what differs from the previous release (right now one
has to sort of search through ChangeLog for references to the release
event).

(OTOH it means more files to search for a particular change, if you
don't have access to the git logs.)

However, *IF* we're going to continue to maintain ChangeLog, I'd
prefer that we continue maintaining it in its present form.

Re: ChangeLogs (Re: GH:zsh-users/zsh-completions.)

[Oliver Kiddle]

Bart wrote:
> It would actually be OK with me to stop maintaining a monolithic
> ChangeLog.  It would be more useful to generate a "release notes" file
> that has only the changes since the last such file.  That would allow
> manual corrections to said file to be preserved without concern that
> they'd be stepped on by the next auto-generate, and make it a lot
> easier to see what differs from the previous release (right now one
> has to sort of search through ChangeLog for references to the release
> event).

With auto-generating ChangeLog entries, I'd expect that you'd pass the
tag of the last release to the script. So no old ChangeLog entries would
ever be stepped on by a later auto-generation. That is irrespective of
whether the output is appended to an existing file or a new file is
created for each release. I forget exactly how Frank's script worked.

> (OTOH it means more files to search for a particular change, if you
> don't have access to the git logs.)

I don't see that as much of a problem. I nearly always do have access to
the git logs. And for old history, Changelog is already separated even
if that was originally done because CVS started to get slow once the
file got big. And I can see that for someone who does want to browse the
ChangeLog, getting just the new entries is useful: much as I often
follow an update with git log @\{1\}..

> However, *IF* we're going to continue to maintain ChangeLog, I'd
> prefer that we continue maintaining it in its present form.

I don't see any reason to change the basic form.

Oliver