Next release

Next release

[Peter Stephenson]

As 4.3 seems to be pretty stable I'd like to release 5.0 shortly without
any further major changes.  The release number won't change until I
actually do that --- the policy is that version numbers always
increment, so 5.0_mumble comes after 5.0 --- although nearer the time
when everything looks ready I may bump the number to 4.99-test-X for the
final test releases just to indicate the intention.

The only significant thing to do for this is rework the source
documentation (NEWS, release notes, etc.) to show changes since 4.2
rather than within 4.3.  If anyone thinks they can make a good attempt
at this, they're welcome.  Otherwise, I will try to make a start on
that.

It would also be useful to document any bugs or major unexpected
restrictions that aren't already documented.  I'm aware of a couple of
weak areas in completion: correspondence classes don't handle multibyte
characters, and nested quoted completion where the contents of the
quotes are interpreted non-trivial (e.g. as a command line by a call to
another shell) are buggy.  This is *not* a call for feature requests.
Any undocumented derogations from POSIX behaviour can be added to the
FAQ.

If you think there's anything significant left to do, it would be a good
time either to do it or try to persuade someone else (good luck with
that).

-- 
Peter Stephenson <pws@csr.com>            Software Engineer
Tel: +44 (0)1223 692070                   Cambridge Silicon Radio Limited
Churchill House, Cambridge Business Park, Cowley Road, Cambridge, CB4 0WZ, UK


Member of the CSR plc group of companies. CSR plc registered in England and Wales, registered number 4187346, registered office Churchill House, Cambridge Business Park, Cowley Road, Cambridge, CB4 0WZ, United Kingdom
More information can be found at www.csr.com. Follow CSR on Twitter at http://twitter.com/CSR_PLC and read our blog at www.csr.com/blog

Re: Next release

[Bart Schaefer]

On Dec 9,  2:11pm, Peter Stephenson wrote:
}
} If you think there's anything significant left to do, it would be a good
} time either to do it or try to persuade someone else (good luck with
} that).

I still have uncommitted the change to add $state_descr to _arguments
and _values and reference it in _zle (workers/29766).  Do we want?

I also have workers/29049 (attempt to restore command line when canceling
out of menu-select) but I don't think it's actually correct.

Re: Next release

[Peter Stephenson]

On Fri, 9 Dec 2011 08:37:14 -0800
Bart Schaefer <schaefer@brasslantern.com> wrote:
> I still have uncommitted the change to add $state_descr to _arguments
> and _values and reference it in _zle (workers/29766).  Do we want?

Seems reasonable to include it, given that the shell probably isn't
going to be come object-orientated any time soon.

-- 
Peter Stephenson <pws@csr.com>            Software Engineer
Tel: +44 (0)1223 692070                   Cambridge Silicon Radio Limited
Churchill House, Cambridge Business Park, Cowley Road, Cambridge, CB4 0WZ, UK


Member of the CSR plc group of companies. CSR plc registered in England and Wales, registered number 4187346, registered office Churchill House, Cambridge Business Park, Cowley Road, Cambridge, CB4 0WZ, United Kingdom
More information can be found at www.csr.com. Follow CSR on Twitter at http://twitter.com/CSR_PLC and read our blog at www.csr.com/blog

Re: Next release

[Frank Terbeck]

Peter Stephenson wrote:
> As 4.3 seems to be pretty stable I'd like to release 5.0 shortly without
> any further major changes.
[...]

While this is coming up, I'd like to bring up the following from a mail from
Peter in January of the year¹:

[...]
| CVS is still down.  It sounds like it's probably time to move to git
| after the next stable release, nobody's suggested replacing it with an
| even more trendy system yet...
[...]

I don't know if that's still something people want. But I thought I'd bring
it up again anyway. FWIW, the FVWM folks were planning a similar move and
one of their developers (Thomas Adam) wrote a lengthy mail describing how
it could work:

  <http://www.mail-archive.com/fvwm-workers@fvwm.org/msg02470.html>

They had a similar starting point as zsh has. One major development branch
in CVS and a working git mirror in place.

Thomas later followed up on himself with the following mail regarding the
ChangeLog file:

  <http://www.mail-archive.com/fvwm-workers@fvwm.org/msg02471.html>

...and I couldn't agree more.

I don't know if dropping the stable- vs development versions, is something
that would work for zsh (although I think it could - everybody uses 4.3.x
anyway) and I also don't know if there would be as much use of public topic
branches as Thomas suggests, because that probably only makes sense when
big features are being added. But all in all, I think he makes a lot of
relevant points that might be transferable to zsh development as well.

If there is someone who doesn't know zsh has a working git mirror, yet,
the browsable gitweb is here:

  <http://zsh.git.sourceforge.net/git/gitweb.cgi?p=zsh/zsh>

and the clone address is this:

  <git://zsh.git.sf.net/gitroot/zsh/zsh>

Regards, Frank

¹ <http://www.zsh.org/mla/workers//2011/msg00109.html>

Re: Next release

[Phil Pennock]

On 2011-12-09 at 14:11 +0000, Peter Stephenson wrote:
> It would also be useful to document any bugs or major unexpected
> restrictions that aren't already documented.

I only implemented metafy/unmetafy for the zsh/pcre module, not the
zsh/regex module which provides the system extended regexp support.

% [[ → =~ ^(.) ]] && print $match
→
% unsetopt rematchpcre
% [[ → =~ ^(.) ]] && print $match
?
%

On the same box, bash (not using PCRE):
$ [[ → =~ ^(.) ]] && echo $BASH_REMATCH
→
$

So clearly the system regex library can handle UTF-8 just fine on this
box, so I have a place to test and might get around to it sometime soon.

-Phil

Re: Next release

[Peter Stephenson]

On Fri, 09 Dec 2011 20:50:27 +0100
Frank Terbeck <ft@bewatermyfriend.org> wrote:
> I don't know if that's still something people want. But I thought I'd bring
> it up again anyway. FWIW, the FVWM folks were planning a similar move and
> one of their developers (Thomas Adam) wrote a lengthy mail describing how
> it could work:
> 
>   <http://www.mail-archive.com/fvwm-workers@fvwm.org/msg02470.html>
> 
> They had a similar starting point as zsh has. One major development branch
> in CVS and a working git mirror in place.

I think it's generally felt moving to git would be sensible and wouldn't
be too much work, given what's already been done with the mirror.

That message seems to be mostly about branch structure which isn't
really relevant to us; our case is much simpler.  Obviously the ease of
people having their own private areas without reference to the main
repository is a big gain, but that's up to them.
 
> Thomas later followed up on himself with the following mail regarding the
> ChangeLog file:
> 
>   <http://www.mail-archive.com/fvwm-workers@fvwm.org/msg02471.html>
> 
> ...and I couldn't agree more.

I'd prefer to have the ChangeLog, at least to begin with.  I find it
much more visible; I'm planning to spend as little time as I can playing
with source control, whose job is to stay in the background while I look
at the files (and I find git infuriatingly geeky).  If we get rid of it
on a day-to-day basis, we would need to get into the habit of including
all the same information in commits --- which is a perfectly reasonable
aim, particularly when the notion of changesets becomes meaningful.
Generating it at the time of a release rather than immediately might be
something to aim at.  If we get to the point where we have a simple
utility (i.e. doesn't demand detailed knowledge of git) that can
generate a readable one, that becomes possible.

> I don't know if dropping the stable- vs development versions, is something
> that would work for zsh (although I think it could - everybody uses 4.3.x
> anyway)

We've only had separate development branches when needed for long term
work on particular features, first ZLE widgets and then multibyte
characters.  I don't think there's any call for a separate branch after
the next stable release is made --- though it would be good to get test
releases spread a bit further than at present.  I wonder if it would be
sensible to use the Sourceforge zsh-dev area for those.

> and I also don't know if there would be as much use of public topic
> branches as Thomas suggests, because that probably only makes sense when
> big features are being added. But all in all, I think he makes a lot of
> relevant points that might be transferable to zsh development as well.

Feel free to bring up anything you think is relevant --- other than the
basic move I didn't see much that seemed to affect our much simpler case
--- but obviously anything that makes administration more complicated is
out (there's no reason moving to git should generally have that effect,
though).

-- 
Peter Stephenson <p.w.stephenson@ntlworld.com>
Web page now at http://homepage.ntlworld.com/p.w.stephenson/

Re: Next release

[Frank Terbeck]

Peter Stephenson wrote:
> Frank Terbeck <ft@bewatermyfriend.org> wrote:
[...]
> That message seems to be mostly about branch structure which isn't
> really relevant to us; our case is much simpler.  Obviously the ease of
> people having their own private areas without reference to the main
> repository is a big gain, but that's up to them.

FVWM is pretty much in maintenance-only mode for a while now, so that
mail was merely to show possible development models, which might be a
helpful insight given that not everybody uses git regularly.

>> Thomas later followed up on himself with the following mail regarding the
>> ChangeLog file:
>> 
>>   <http://www.mail-archive.com/fvwm-workers@fvwm.org/msg02471.html>
>> 
>> ...and I couldn't agree more.
>
> I'd prefer to have the ChangeLog, at least to begin with.  I find it
> much more visible;

Really? I find manual ChangeLog updates (even with the help of emacs'
`add-change-log-entry') to be the single most annoying thing about CVS
from a mere user's perspective, because it doesn't work with changesets.

It also makes merging different changes virtually impossible, because
there will always be a conflict at the top of the ChangeLog file
(although I hear people have automatic merge drivers for that now¹).

> I'm planning to spend as little time as I can playing
> with source control, whose job is to stay in the background while I look
> at the files (and I find git infuriatingly geeky).  If we get rid of it
> on a day-to-day basis, we would need to get into the habit of including
> all the same information in commits --- which is a perfectly reasonable
> aim, particularly when the notion of changesets becomes meaningful.
> Generating it at the time of a release rather than immediately might be
> something to aim at.  If we get to the point where we have a simple
> utility (i.e. doesn't demand detailed knowledge of git) that can
> generate a readable one, that becomes possible.

Yes, ChangeLog conversion could be automated from the output of "git
log". A one line approach might be as "easy" as this:

 git --no-pager log --format="%ai %aN %n%n%x09* %s%d%n" $(git describe --abbrev=0)..

...which would make for a nice alias in ~/.gitconfig. But the result
could be better. And people have done better. That's not rocket science.
Either we use an existing script from someone else, or we cook up one of
our own.

>> I don't know if dropping the stable- vs development versions, is something
>> that would work for zsh (although I think it could - everybody uses 4.3.x
>> anyway)
>
> We've only had separate development branches when needed for long term
> work on particular features, first ZLE widgets and then multibyte
> characters.
[...]

Agreed. And even if we'd need a feature branch for stuff like that, it's
extremely easy to one such branch in git (as Thomas from FVWM outlined
in his mail).

[...]
> Feel free to bring up anything you think is relevant --- other than the
> basic move I didn't see much that seemed to affect our much simpler case
> --- but obviously anything that makes administration more complicated is
> out (there's no reason moving to git should generally have that effect,
> though).

Yes. Git can be used with an CVS-like workflow to a central server just
fine. And almost exactly the same way as with CVS (except that you make
a commit locally first and push the complete commit over to the server
after that).

It's absolutely up to the individual developer to decide how much of
git's feature-set he/she wants to use locally.

I also think that there are quite a number of apt git users on -workers,
who should be able to assist if something odd comes up (which may or may
not happen).


As for the actual move to git: Wayne is keeping the CVS repository in
sync pretty darn well and I guess it's just a setting somewhere in the
sourceforge configuration to turn off CVS commits and enable commit
pushing into the git repository. I don't know the sourceforge admin
interface, but I'm sure Wayne will have a pretty good idea on how to do
that final switch-over.


Regards, Frank

¹ <http://gcc.gnu.org/wiki/GitMirror#git-merge-changelog> (I didn't try
  that one)

Re: Next release

[Peter Stephenson]

On Sat, 10 Dec 2011 20:20:10 +0100
Frank Terbeck <ft@bewatermyfriend.org> wrote:
> Yes, ChangeLog conversion could be automated from the output of "git
> log". A one line approach might be as "easy" as this:
> 
>  git --no-pager log --format="%ai %aN %n%n%x09* %s%d%n" $(git describe --abbrev=0)..
> 
> ...which would make for a nice alias in ~/.gitconfig. But the result
> could be better. And people have done better. That's not rocket science.
> Either we use an existing script from someone else, or we cook up one of
> our own.

I think when we can get to the point where I can type
"Util/changelog.sh", or whatever, and recreate the ChangeLog since the
last release, or the release label/change specified as an argument, I
will be entirely happy.  However, that's a prerequisite, rather than a
reason, for abandoning it.

-- 
Peter Stephenson <p.w.stephenson@ntlworld.com>
Web page now at http://homepage.ntlworld.com/p.w.stephenson/

Re: Next release

[Frank Terbeck]

Peter Stephenson wrote:
> I think when we can get to the point where I can type
> "Util/changelog.sh", or whatever, and recreate the ChangeLog since the
> last release, or the release label/change specified as an argument, I
> will be entirely happy.  However, that's a prerequisite, rather than a
> reason, for abandoning it.

That should not be a problem. And obviously, if you'd still like to keep
a manual ChangeLog after all, I won't complain. That way I'll get to try
that merge-driver. ;)

Regards, Frank

_arguments and state_descr (Re: Next release)

[Bart Schaefer]

On Dec 9,  4:42pm, Peter Stephenson wrote:
} Subject: Re: Next release
}
} On Fri, 9 Dec 2011 08:37:14 -0800
} Bart Schaefer <schaefer@brasslantern.com> wrote:
} > I still have uncommitted the change to add $state_descr to _arguments
} > and _values and reference it in _zle (workers/29766).  Do we want?
} 
} Seems reasonable to include it, given that the shell probably isn't
} going to be come object-orientated any time soon.

Here's the proposed final diff, just to get it a recent zsh-workers
article number.  Note that in writing the doc I discovered that what
we've been calling the "description" is actually termed the "message"
in the existing documentation, although it is passed to _wanted in
the description position.

Does that have any influence on what the array should be named?  I've
never been entirely happy with "state_descr".


Index: Completion/Base/Core/_main_complete
===================================================================
RCS file: /cvsroot/zsh/zsh/Completion/Base/Core/_main_complete,v
retrieving revision 1.13
diff -u -r1.13 _main_complete
--- Completion/Base/Core/_main_complete	24 May 2011 01:09:46 -0000	1.13
+++ Completion/Base/Core/_main_complete	12 Dec 2011 16:25:50 -0000
@@ -23,7 +23,8 @@
 local func funcs ret=1 tmp _compskip format nm call match min max i num\
       _completers _completer _completer_num curtag _comp_force_list \
       _matchers _matcher _c_matcher _matcher_num _comp_tags _comp_mesg  \
-      mesg str context state line opt_args val_args curcontext="$curcontext" \
+      mesg str context state state_descr line opt_args val_args \
+      curcontext="$curcontext" \
       _last_nmatches=-1 _last_menu_style _def_menu_style _menu_style sel \
       _tags_level=0 \
       _saved_exact="${compstate[exact]}" \
Index: Completion/Base/Utility/_arguments
===================================================================
RCS file: /cvsroot/zsh/zsh/Completion/Base/Utility/_arguments,v
retrieving revision 1.22
diff -u -r1.22 _arguments
--- Completion/Base/Utility/_arguments	17 Nov 2008 10:37:37 -0000	1.22
+++ Completion/Base/Utility/_arguments	12 Dec 2011 16:25:50 -0000
@@ -344,6 +344,7 @@
 
   context=()
   state=()
+  state_descr=()
 
   while true; do
     while _tags; do
@@ -376,6 +377,7 @@
 	      if (( ! $state[(I)$action] )); then
                 comparguments -W line opt_args
                 state+=( "$action" )
+                state_descr+=( "$descr" )
 	        if [[ -n "$usecc" ]]; then
 	          curcontext="${oldcontext%:*}:$subc"
 	        else
Index: Completion/Base/Utility/_values
===================================================================
RCS file: /cvsroot/zsh/zsh/Completion/Base/Utility/_values,v
retrieving revision 1.12
diff -u -r1.12 _values
--- Completion/Base/Utility/_values	28 Aug 2009 15:10:39 -0000	1.12
+++ Completion/Base/Utility/_values	12 Dec 2011 16:25:50 -0000
@@ -87,6 +87,7 @@
   if [[ "$action" = -\>* ]]; then
     compvalues -v val_args
     state="${${action[3,-1]##[ 	]#}%%[ 	]#}"
+    state_descr="$descr"
     if [[ -n "$usecc" ]]; then
       curcontext="${oldcontext%:*}:$subc"
     else
Index: Completion/Zsh/Command/_zle
===================================================================
RCS file: /cvsroot/zsh/zsh/Completion/Zsh/Command/_zle,v
retrieving revision 1.4
diff -u -r1.4 _zle
--- Completion/Zsh/Command/_zle	13 Sep 2010 08:49:23 -0000	1.4
+++ Completion/Zsh/Command/_zle	12 Dec 2011 16:25:51 -0000
@@ -44,7 +44,7 @@
       '(-)*:widget arguments: ' && ret=0
     ;;
   (widget*)
-    _wanted -C "$context[1]" widgets expl widget compadd -k widgets && ret=0
+    _wanted -C "$context[1]" widgets expl "${state_descr[1]:-widget}" compadd -k widgets && ret=0
     ;&
   (function)
     [[ $state[1] != *function ]] ||	# Handle fall-through
Index: Doc/Zsh/compsys.yo
===================================================================
RCS file: /cvsroot/zsh/zsh/Doc/Zsh/compsys.yo,v
retrieving revision 1.245
diff -u -r1.245 compsys.yo
--- Doc/Zsh/compsys.yo	11 Dec 2011 17:48:27 -0000	1.245
+++ Doc/Zsh/compsys.yo	12 Dec 2011 16:25:56 -0000
@@ -3687,10 +3687,12 @@
 for generating completions.  For example, functions that implement a state
 machine can use this type of action.
 
-Where tt(_arguments) encounters a `tt(->)var(string)', it will strip
-all leading and trailing whitespace from var(string) and set the array
-tt(state) to the set of all var(strings)s for which an action is to be
-performed.
+Where tt(_arguments) encounters var(action) in the `tt(->)var(string)'
+format, it will strip all leading and trailing whitespace from var(string)
+and set the array tt(state) to the set of all var(string)s for which an
+action is to be performed.  The elements of the array tt(state_descr) are
+assigned the corresponding var(message) field from each var(optarg)
+containing such an var(action).
 
 By default and in common with all other well behaved completion
 functions, _arguments returns status zero if it was able to add matches and
@@ -3698,7 +3700,8 @@
 tt(_arguments) will instead return a status of 300 to indicate that
 tt($state) is to be handled.
 
-In addition to tt($state), tt(_arguments) also sets the global
+In addition to tt($state) and tt($state_descr), tt(_arguments) also
+sets the global
 parameters `tt(context)', `tt(line)' and `tt(opt_args)' as described
 below, and does not reset any changes made to the special parameters
 such as tt(PREFIX) and tt(words).  This gives the calling function the
@@ -3708,7 +3711,7 @@
 one action containing a `tt(->)var(string)' must therefore declare
 appropriate local parameters:
 
-example(local context state line
+example(local context state state_descr line
 typeset -A opt_args)
 
 to prevent tt(_arguments) from altering the global environment.
@@ -4794,15 +4797,17 @@
 The associative array tt(val_args) is used to report values and their
 arguments; this works similarly to the tt(opt_args) associative array
 used by tt(_arguments).  Hence the function calling tt(_values) should
-declare the local parameters tt(state), tt(line), tt(context) and
-tt(val_args):
+declare the local parameters tt(state), tt(state_descr), tt(line),
+tt(context) and tt(val_args):
 
-example(local context state line
+example(local context state state_descr line
 typeset -A val_args)
 
 when using an action of the form `tt(->)var(string)'.  With this
 function the tt(context) parameter will be set to the name of the
-value whose argument is to be completed.
+value whose argument is to be completed.  Note that for tt(_values),
+the tt(state) and tt(state_descr) are scalars rather than arrays.
+Only a single matching state is returned.
 
 Note also that tt(_values) normally adds the character used as the
 separator between values as an auto-removable suffix (similar to a

Re: _arguments and state_descr (Re: Next release)

[Peter Stephenson]

On Mon, 12 Dec 2011 08:28:18 -0800
Bart Schaefer <schaefer@brasslantern.com> wrote:
> Here's the proposed final diff, just to get it a recent zsh-workers
> article number.  Note that in writing the doc I discovered that what
> we've been calling the "description" is actually termed the "message"
> in the existing documentation, although it is passed to _wanted in
> the description position.
> 
> Does that have any influence on what the array should be named?  I've
> never been entirely happy with "state_descr".

Well, you could call it "state_message", or perhaps better
"state_messages".

-- 
Peter Stephenson <pws@csr.com>            Software Engineer
Tel: +44 (0)1223 692070                   Cambridge Silicon Radio Limited
Churchill House, Cambridge Business Park, Cowley Road, Cambridge, CB4 0WZ, UK


Member of the CSR plc group of companies. CSR plc registered in England and Wales, registered number 4187346, registered office Churchill House, Cambridge Business Park, Cowley Road, Cambridge, CB4 0WZ, United Kingdom
More information can be found at www.csr.com. Follow CSR on Twitter at http://twitter.com/CSR_PLC and read our blog at www.csr.com/blog

Re: _arguments and state_descr (Re: Next release)

[Bart Schaefer]

On Dec 12,  4:46pm, Peter Stephenson wrote:
}
} Well, you could call it "state_message", or perhaps better
} "state_messages".

I'd call it "state_messages" if "state" were also plural, but neither
that nor "context" is.

I'm tempted toward just "message" to go with the other two, but we
probably should be sticking with things unlikely to clash with other
names in the scope ... so I guess I'll just leave it "state_descr"
if no one has a strong opinion.

ChangeLog generation (was: Re: Next release)

[Frank Terbeck]

Peter Stephenson wrote:
[...]
> I think when we can get to the point where I can type
> "Util/changelog.sh", or whatever, and recreate the ChangeLog since the
> last release, or the release label/change specified as an argument, I
> will be entirely happy.  However, that's a prerequisite, rather than a
> reason, for abandoning it.

I had some spare time, being on a train, and I came up with this:

  <http://ft.bewatermyfriend.org/comp/genchangelog.html>

That should be good enough (minus bugs, obviously).

Regards, Frank

Re: ChangeLog generation (was: Re: Next release)

[Peter Stephenson]

On Tue, 24 Jan 2012 14:03:59 +0100
Frank Terbeck <ft@bewatermyfriend.org> wrote:
> I had some spare time, being on a train, and I came up with this:
> 
>   <http://ft.bewatermyfriend.org/comp/genchangelog.html>
> 
> That should be good enough (minus bugs, obviously).

That's useful, thanks.

We still need some way of associating the mailing list posting with the
change set, which is a bit of a puzzle since you are likely to commit it
to your local repository first.  It doesn't need to be in comments (I
couldn't see any way of updating them when pushing), it could be in some
other metadata, so there may well be some workaround.  We're sunk
without it, though, since tracing changes back to the discussion about
it on the mailing list is crucial for working out the intention behind
changes.

Ultimately this is no more than the usually necessity for tracking from
an archive to a bug database (as with Perforce's notion of jobs, for
example, which would do this nicely), so somebody's bound to have
thought about it.

-- 
Peter Stephenson <p.w.stephenson@ntlworld.com>
Web page now at http://homepage.ntlworld.com/p.w.stephenson/

Re: ChangeLog generation (was: Re: Next release)

[Bart Schaefer]

On Jan 24,  2:03pm, Frank Terbeck wrote:
}
} Peter Stephenson wrote:
} [...]
} > I think when we can get to the point where I can type
} > "Util/changelog.sh", or whatever, and recreate the ChangeLog
} 
} I had some spare time, being on a train, and I came up with this:
} 
}   <http://ft.bewatermyfriend.org/comp/genchangelog.html>
} 
} That should be good enough (minus bugs, obviously).

Hrm.  This is nice work and a pretty good compromise, but just in the
course of looking through the sample output you included on that web
page, there appear several cases where the existing ChangeLog is
actually more accurate (thanks to having been repaired) than the commit
log entries from which it would be "regenerated" by the script.

One of my pet peeves with automating things in this way is that it often
means typographical errors get enshrined for eternity, sometimes with
confusing results when someone else goes looking through the logs.
(Don't get me started on the inability to edit comments in bugzilla.)

Also ... I'm not that familiar with how git organizes commits, i.e.,
what determines the list/of/change/files for a particular hash-sum.
In an ideal world the commit entry for a given file would discuss only
the changes relevant to that specific file, even if there were a bunch
of changed files that should all be considered as a group in that the
changes to one don't make sense without the changes to another.  I
have often found myself doing several "cvs commit" to cover each subset
of the files that were edited, and then a single commit of ChangeLog
with a composite description to give the context in which all the other
commits were made.

Is anything like that possible here?

At the very least we're going to need to come up with a new convention
for the commit logs so that the mailing list article IDs are not lost.

Re: ChangeLog generation

[Frank Terbeck]

Peter Stephenson wrote:
[...]
> We still need some way of associating the mailing list posting with the
> change set, which is a bit of a puzzle since you are likely to commit it
> to your local repository first.  It doesn't need to be in comments (I
> couldn't see any way of updating them when pushing), it could be in some
> other metadata, so there may well be some workaround.  We're sunk
> without it, though, since tracing changes back to the discussion about
> it on the mailing list is crucial for working out the intention behind
> changes.
[...]

This sounds like a job for `git-notes'¹², which is additional data you
can stick to an object (like a commit) without changing the object
itself (leaving the hash-sums of the history intact).

My experience with them is limited, but that shouldn't be the biggest
problem. ;)

Regards, Frank

¹ <http://schacon.github.com/git/git-notes.html>
² <http://progit.org/2010/08/25/notes.html>

Re: ChangeLog generation

[Frank Terbeck]

Bart Schaefer wrote:
[...]
> Hrm.  This is nice work and a pretty good compromise, but just in the
> course of looking through the sample output you included on that web
> page, there appear several cases where the existing ChangeLog is
> actually more accurate (thanks to having been repaired) than the commit
> log entries from which it would be "regenerated" by the script.
>
> One of my pet peeves with automating things in this way is that it often
> means typographical errors get enshrined for eternity, sometimes with
> confusing results when someone else goes looking through the logs.
> (Don't get me started on the inability to edit comments in bugzilla.)

Well, with the script, you can change the generated text, all you want.
Just leave the hash-sums of the individual entries intact. They are used
by the script were to pick up generation in the next run.

The old text in the generated changelog is not re-generated and manual
changes will be kept and not overridden. If that would happen, that
would be a bug.

I do hate typos, too. But once a typo is in a commit message on the
central repository, you can't fix it in the commit message anymore
(well, you can, but you'd change history and all hash-sums after your
typo fix would be changed - that's something the git community advocates
against, because it screws everybody who has got work that's based on
the old tree).

The way to prevent that, is this: You usually prepare patches to the
mailing list using `git format-patch' (which you can conveniently send
by using `git send-email'). Those patches contain the complete commit
message, however detailed it may be.

Reviewers should try to spot typos, so the author can fix them in
his/her own local repository. All parts of a local repository, that are
not in the central repository, yet, can be changed over and over again
until the author is satisfied with the result.


If a typo still makes it to the changelog (note, that the script only
picks up the first like of a git-commit message¹ - the subject, so to
speak), you can fix it up manually; because generation is done
incrementally, like I said above.

> Also ... I'm not that familiar with how git organizes commits, i.e.,
> what determines the list/of/change/files for a particular hash-sum.

Generally speaking, git doesn't track files. It tracks the content of
the files. And thus changes are recorded with the whole tree in mind. As
change-sets.

I think that makes very much sense. In a commit message you'd then
describe the change that is introduced by all the changes to all touched
files. A commit should only cover one such change, like a new feature or
option.

I'm also a fan of long detailed commit messages. ;)

> In an ideal world the commit entry for a given file would discuss only
> the changes relevant to that specific file, even if there were a bunch
> of changed files that should all be considered as a group in that the
> changes to one don't make sense without the changes to another.  I
> have often found myself doing several "cvs commit" to cover each subset
> of the files that were edited, and then a single commit of ChangeLog
> with a composite description to give the context in which all the other
> commits were made.
>
> Is anything like that possible here?

Sure. You can mark a single line from a set of changes across multiple
files for commit and just commit that. Or a single hunk. Or indeed a
single file. Git offers full control over what's going into the next
commit and what doesn't.

And sometimes, when I didn't pay attention and make many unrelated
changes, I go fire up "git gui" and dissect my changes into logical,
atomic commits, to keep a project's history useful. (Having atomic
commits makes it easy to revert changes, too, if that would be needed at
some point in the future.)

> At the very least we're going to need to come up with a new convention
> for the commit logs so that the mailing list article IDs are not lost.

Like I said in my reply to Peter, I think this is a job for `git-notes'.


Regards, Frank


¹ A quick note about git's commit message convention: A message starts
with a short descriptive one-line title followed by an *empty* line,
followed by a body of arbitrary length. And git's `format-patch'
actually puts that title line into the generated email's Subject:
header, the lengthy body obviously goes into the email's body.