Use of "Action stamps" in commit messages (WAS: [Emacs-diffs] master babe0d4: Rearrange definition of zerop in subr.el)

Use of "Action stamps" in commit messages (WAS: [Emacs-diffs] master babe0d4: Rearrange definition of zerop in subr.el)

[Noam Postavsky]

.On 12 July 2018 at 11:34, Basil L. Contovounesios <contovob@tcd.ie> wrote:

> from CONTRIBUTE:
>
>   One way to identify revisions is by quoting their summary line.
>   Another is with an action stamp - an RFC3339 date followed by !
>   followed by the committer's email - for example,
>   "2014-01-16T05:43:35Z!esr@thyrsus.com".

This reminds that I'd like to remove this "Action stamp" thing as
commit message convention. Action stamps are fine for what they were
designed for: acting as a unique commit id for the repository
conversion software "reposurgeon", but they are not very friendly to
human readers.

A date followed by the summary line is sufficient to identify a commit
in a vc system agnostic way, reads nicer, and gives more info up front
to a human.

See also Bug#20609.

https://debbugs.gnu.org/cgi/bugreport.cgi?bug=20609

Re: Use of "Action stamps" in commit messages (WAS: [Emacs-diffs] master babe0d4: Rearrange definition of zerop in subr.el)

[Eli Zaretskii]

> From: Noam Postavsky <npostavs@gmail.com>
> Date: Fri, 13 Jul 2018 05:13:38 -0400
> Cc: Karl Fogel <kfogel@red-bean.com>, Paul Eggert <eggert@cs.ucla.edu>,
> 	Emacs developers <emacs-devel@gnu.org>
> 
> >   One way to identify revisions is by quoting their summary line.
> >   Another is with an action stamp - an RFC3339 date followed by !
> >   followed by the committer's email - for example,
> >   "2014-01-16T05:43:35Z!esr@thyrsus.com".
> 
> This reminds that I'd like to remove this "Action stamp" thing as
> commit message convention.

No objections here.  They are used quite rarely anyway.

Re: Use of "Action stamps" in commit messages

[Andy Moreton]

On Fri 13 Jul 2018, Noam Postavsky wrote:

> .On 12 July 2018 at 11:34, Basil L. Contovounesios <contovob@tcd.ie> wrote:
>
>> from CONTRIBUTE:
>>
>>   One way to identify revisions is by quoting their summary line.
>>   Another is with an action stamp - an RFC3339 date followed by !
>>   followed by the committer's email - for example,
>>   "2014-01-16T05:43:35Z!esr@thyrsus.com".
>
> This reminds that I'd like to remove this "Action stamp" thing as
> commit message convention. Action stamps are fine for what they were
> designed for: acting as a unique commit id for the repository
> conversion software "reposurgeon", but they are not very friendly to
> human readers.
>
> A date followed by the summary line is sufficient to identify a commit
> in a vc system agnostic way, reads nicer, and gives more info up front
> to a human.
>
> See also Bug#20609.
>
> https://debbugs.gnu.org/cgi/bugreport.cgi?bug=20609

The Linux kernel convention is nicer: the (shortened) commit id,
followed by a space and the commit summary line, e.g.

Fixes: 1222ff5275 ("Don't skip epg-tests even with gpg 2.0 (Bug#23561)")

This ensures that the format is human readable, is easy to parse for
scripting, and identifies the right commit even if the shortened commit
id is not unique.

     AndyM

Re: Use of "Action stamps" in commit messages

[Eli Zaretskii]

> From: Andy Moreton <andrewjmoreton@gmail.com>
> Date: Fri, 13 Jul 2018 13:59:32 +0100
> 
> The Linux kernel convention is nicer: the (shortened) commit id,
> followed by a space and the commit summary line, e.g.
> 
> Fixes: 1222ff5275 ("Don't skip epg-tests even with gpg 2.0 (Bug#23561)")

We wanted an ID that is not specific to Git, having learned that a
hard way from the period we used bzr revision numbers.

> This ensures that the format is human readable, is easy to parse for
> scripting, and identifies the right commit even if the shortened commit
> id is not unique.

They will stop being useful if we ever change our VCS.

Re: Use of "Action stamps" in commit messages

[Andy Moreton]

On Fri 13 Jul 2018, Eli Zaretskii wrote:

>> From: Andy Moreton <andrewjmoreton@gmail.com>
>> Date: Fri, 13 Jul 2018 13:59:32 +0100
>> 
>> The Linux kernel convention is nicer: the (shortened) commit id,
>> followed by a space and the commit summary line, e.g.
>> 
>> Fixes: 1222ff5275 ("Don't skip epg-tests even with gpg 2.0 (Bug#23561)")
>
> We wanted an ID that is not specific to Git, having learned that a
> hard way from the period we used bzr revision numbers.

Using the summary line of the commit message is still useful to help
identify the right changeset (as long as you train popel to stop writing
bad commit messages like "fix last commit").

>> This ensures that the format is human readable, is easy to parse for
>> scripting, and identifies the right commit even if the shortened commit
>> id is not unique.
>
> They will stop being useful if we ever change our VCS.

That is unlikely for the forseeable future.

    AndyM

Re: Use of "Action stamps" in commit messages

[Eli Zaretskii]

> From: Andy Moreton <andrewjmoreton@gmail.com>
> Date: Fri, 13 Jul 2018 16:01:28 +0100
> 
> >> Fixes: 1222ff5275 ("Don't skip epg-tests even with gpg 2.0 (Bug#23561)")
> >
> > We wanted an ID that is not specific to Git, having learned that a
> > hard way from the period we used bzr revision numbers.
> 
> Using the summary line of the commit message is still useful to help
> identify the right changeset (as long as you train popel to stop writing
> bad commit messages like "fix last commit").

Yes, but adding a date makes the reference more precise.

> > They will stop being useful if we ever change our VCS.
> 
> That is unlikely for the forseeable future.

Yes, we thought that way, too, in the past.  We were wrong.

Re: Use of "Action stamps" in commit messages

[Radon Rosborough]

> They will stop being useful if we ever change our VCS.

Maybe I'm missing something, but -- if we change to a different VCS,
we are going to have to rewrite all the history anyway. Why would it
be difficult to have a filter that goes through and replaces all the
Git commit IDs with the corresponding ones for the new VCS?

Sure, it'd be annoying and possibly fairly difficult, but changing to
a different VCS is a thing that -- even if it does happen, which I
doubt -- will happen extremely rarely.

I can understand if we avoid using Git commit IDs in the code, where
we don't want to rewrite history at all, but why not in the commit
messages?

Re: Use of "Action stamps" in commit messages

[Yuri Khan]

On Sat, Jul 14, 2018 at 12:09 AM Radon Rosborough <radon.neon@gmail.com> wrote:
>
> > They will stop being useful if we ever change our VCS.
>
> Maybe I'm missing something, but -- if we change to a different VCS,
> we are going to have to rewrite all the history anyway. Why would it
> be difficult to have a filter that goes through and replaces all the
> Git commit IDs with the corresponding ones for the new VCS?

Because it is hard for an automatic tool to tell Git commit IDs from
unrelated hexadecimal numbers.

Re: Use of "Action stamps" in commit messages

[Radon Rosborough]

>> Maybe I'm missing something, but -- if we change to a different VCS,
>> we are going to have to rewrite all the history anyway. Why would it
>> be difficult to have a filter that goes through and replaces all the
>> Git commit IDs with the corresponding ones for the new VCS?
>
> Because it is hard for an automatic tool to tell Git commit IDs from
> unrelated hexadecimal numbers.

The tool will know all the valid Git commit IDs, though. It could
translate unambiguous prefixes of more than 12 characters (or
something) automatically, and then prompt the user to resolve the
rest. It seems to me like translating the whole thing wouldn't be more
than an afternoon's work—are there really that many hexadecimal
numbers that happen to be prefixes of Git commit IDs in commit
messages?

IOW, although there are complications, this is something that would
only happen extremely rarely, and would only have to be done by one
person, and probably won't even happen at all. Whereas the alternative
solution requires all the developers to expend extra mental energy.

Re: Use of "Action stamps" in commit messages

[Eli Zaretskii]

> From: Radon Rosborough <radon.neon@gmail.com>
> Date: Fri, 13 Jul 2018 11:30:11 -0600
> Cc: Eli Zaretskii <eliz@gnu.org>, Andy Moreton <andrewjmoreton@gmail.com>, 
> 	emacs-devel <emacs-devel@gnu.org>
> 
> >> Maybe I'm missing something, but -- if we change to a different VCS,
> >> we are going to have to rewrite all the history anyway. Why would it
> >> be difficult to have a filter that goes through and replaces all the
> >> Git commit IDs with the corresponding ones for the new VCS?
> >
> > Because it is hard for an automatic tool to tell Git commit IDs from
> > unrelated hexadecimal numbers.
> 
> The tool will know all the valid Git commit IDs, though. It could
> translate unambiguous prefixes of more than 12 characters (or
> something) automatically

Git SHA1 signatures don't require 12 digits, 7 are almost always
enough.  And then there's the output of "git describe" as a variant
that should also be supported.

> and then prompt the user to resolve the rest. It seems to me like
> translating the whole thing wouldn't be more than an afternoon's
> work—are there really that many hexadecimal numbers that happen to
> be prefixes of Git commit IDs in commit messages?

You are overly optimistic.  Last time we bumped into this, it required
a lot of non-trivial manual work.

> IOW, although there are complications, this is something that would
> only happen extremely rarely, and would only have to be done by one
> person, and probably won't even happen at all. Whereas the alternative
> solution requires all the developers to expend extra mental energy.

Some problems cannot be worked around.  Its just the way things are.

Re: Use of "Action stamps" in commit messages

[Eli Zaretskii]

> From: Radon Rosborough <radon.neon@gmail.com>
> Date: Fri, 13 Jul 2018 11:07:26 -0600
> Cc: Andy Moreton <andrewjmoreton@gmail.com>, emacs-devel <emacs-devel@gnu.org>
> 
> > They will stop being useful if we ever change our VCS.
> 
> Maybe I'm missing something, but -- if we change to a different VCS,
> we are going to have to rewrite all the history anyway. Why would it
> be difficult to have a filter that goes through and replaces all the
> Git commit IDs with the corresponding ones for the new VCS?

How do you know that a particular string of hex digits is a Git SHA1
of a commit?  A human might be able to make that decision, but a
program that converts the entire repository will be unable to do that
reliably.  The low reliability of such conversions in the pats was
what caused us to adopt the "action stamp" notation.

> Sure, it'd be annoying and possibly fairly difficult, but changing to
> a different VCS is a thing that -- even if it does happen, which I
> doubt -- will happen extremely rarely.

It doesn't matter how rarely this happens, because when it does, you
want the entire project history to still be readable and useful.

Re: Use of "Action stamps" in commit messages

[John Yates]

On Fri, Jul 13, 2018 at 9:46 AM Eli Zaretskii <eliz@gnu.org> wrote:
> They will stop being useful if we ever change our VCS.

One of the glories of ESR's moving Emacs from bzr to git is
degree to which he translated many such constructs.  Were
Emacs to move to another VCS surely there would be some
similar translation activity.  I doubt that such IDs would be
much of a stumbling block.

/john

Re: Use of "Action stamps" in commit messages

[Eli Zaretskii]

> From: John Yates <john@yates-sheets.org>
> Date: Fri, 13 Jul 2018 14:17:40 -0400
> Cc: andrewjmoreton@gmail.com, Emacs developers <emacs-devel@gnu.org>
> 
> On Fri, Jul 13, 2018 at 9:46 AM Eli Zaretskii <eliz@gnu.org> wrote:
> > They will stop being useful if we ever change our VCS.
> 
> One of the glories of ESR's moving Emacs from bzr to git is
> degree to which he translated many such constructs.  Were
> Emacs to move to another VCS surely there would be some
> similar translation activity.  I doubt that such IDs would be
> much of a stumbling block.

They were the last time, and it's at ESR's request that we decided to
use those.  It wasn't an arbitrary decision out of thin air.  We
discussed that at the time.  You are welcome to read those discussions
and raise arguments that were not voiced back there.

Re: Use of "Action stamps" in commit messages

[Paul Eggert]

Eric Raymond designed that format, partly to be robust in the presence
of VC backend changes. I'll send this message to him directly, to give
him a heads-up, as this has been a long thread that he's likely tuned
out of.

On 07/13/2018 04:13 AM, Noam Postavsky wrote:
> .On 12 July 2018 at 11:34, Basil L. Contovounesios <contovob@tcd.ie> wrote:
>
>> from CONTRIBUTE:
>>
>>   One way to identify revisions is by quoting their summary line.
>>   Another is with an action stamp - an RFC3339 date followed by !
>>   followed by the committer's email - for example,
>>   "2014-01-16T05:43:35Z!esr@thyrsus.com".
> This reminds that I'd like to remove this "Action stamp" thing as
> commit message convention. Action stamps are fine for what they were
> designed for: acting as a unique commit id for the repository
> conversion software "reposurgeon", but they are not very friendly to
> human readers.
>
> A date followed by the summary line is sufficient to identify a commit
> in a vc system agnostic way, reads nicer, and gives more info up front
> to a human.
>
> See also Bug#20609.
>
> https://debbugs.gnu.org/cgi/bugreport.cgi?bug=20609

Re: Use of "Action stamps" in commit messages

[Eric S. Raymond]

Paul Eggert <eggert@cs.ucla.edu>:
> Eric Raymond designed that format, partly to be robust in the presence
> of VC backend changes. I'll send this message to him directly, to give
> him a heads-up, as this has been a long thread that he's likely tuned
> out of.
> 
> On 07/13/2018 04:13 AM, Noam Postavsky wrote:
> > .On 12 July 2018 at 11:34, Basil L. Contovounesios <contovob@tcd.ie> wrote:
> >
> >> from CONTRIBUTE:
> >>
> >>   One way to identify revisions is by quoting their summary line.
> >>   Another is with an action stamp - an RFC3339 date followed by !
> >>   followed by the committer's email - for example,
> >>   "2014-01-16T05:43:35Z!esr@thyrsus.com".
> > This reminds that I'd like to remove this "Action stamp" thing as
> > commit message convention. Action stamps are fine for what they were
> > designed for: acting as a unique commit id for the repository
> > conversion software "reposurgeon", but they are not very friendly to
> > human readers.
> >
> > A date followed by the summary line is sufficient to identify a commit
> > in a vc system agnostic way, reads nicer, and gives more info up front
> > to a human.
> >
> > See also Bug#20609.
> >
> > https://debbugs.gnu.org/cgi/bugreport.cgi?bug=20609

If you're going to do this, please at least have mercy on future translators
and use a strict RFC3339 date format the way action stamps do.

I'm against this change because I think in the long term.  Someday Emacs
will change VCSes again.  On the day, whoever is charged with the move is
going to curse the perpetrators if he has to deal with a semi-infinite number
of variant ways of pasting together the data and commit parts of your 
proposed IDs.

I know of two efforts underway to make cgit and git itself aware of the
action-stamp format. Have patience.  Soon enough you'll be able to treat
action stampts as hotlinks that your software will chase for you.
-- 
		<a href="http://www.catb.org/~esr/">Eric S. Raymond</a>

My work is funded by the Internet Civil Engineering Institute: https://icei.org
Please visit their site and donate: the civilization you save might be your own.

Re: Use of "Action stamps" in commit messages

[Eli Zaretskii]

> Date: Fri, 13 Jul 2018 14:15:20 -0400
> From: "Eric S. Raymond" <esr@thyrsus.com>
> Cc: Emacs developers <emacs-devel@gnu.org>
> 
> I'm against this change because I think in the long term.  Someday Emacs
> will change VCSes again.  On the day, whoever is charged with the move is
> going to curse the perpetrators if he has to deal with a semi-infinite number
> of variant ways of pasting together the data and commit parts of your 
> proposed IDs.

I think the idea is that the date/time and the header line identify
the commit well enough to be able to find it using VCS commands.

> I know of two efforts underway to make cgit and git itself aware of the
> action-stamp format. Have patience.  Soon enough you'll be able to treat
> action stampts as hotlinks that your software will chase for you.

I'm not sure having hyperlinks justifies the trouble of having to
concoct those stamps.  In a repository such as we have in Emacs, a
time stamp should allow you to find the commit fairly easily, I think.

Re: Use of "Action stamps" in commit messages

[Eric S. Raymond]

Eli Zaretskii <eliz@gnu.org>:
> I'm not sure having hyperlinks justifies the trouble of having to
> concoct those stamps.  In a repository such as we have in Emacs, a
> time stamp should allow you to find the commit fairly easily, I think.

While this is true, experience leads me to fear a proliferation of
varying and damaged timestamp formats uttered by people in a hurry.

Only a convention as simple and strong as action stamps has any
hope of being effective against this sort of drift.
-- 
		<a href="http://www.catb.org/~esr/">Eric S. Raymond</a>

My work is funded by the Internet Civil Engineering Institute: https://icei.org
Please visit their site and donate: the civilization you save might be your own.

Re: Use of "Action stamps" in commit messages

[Eli Zaretskii]

> Date: Fri, 13 Jul 2018 15:06:15 -0400
> From: "Eric S. Raymond" <esr@thyrsus.com>
> Cc: eggert@cs.ucla.edu, emacs-devel@gnu.org
> 
> Eli Zaretskii <eliz@gnu.org>:
> > I'm not sure having hyperlinks justifies the trouble of having to
> > concoct those stamps.  In a repository such as we have in Emacs, a
> > time stamp should allow you to find the commit fairly easily, I think.
> 
> While this is true, experience leads me to fear a proliferation of
> varying and damaged timestamp formats uttered by people in a hurry.

I think generating the RFC3339 time stamps is more error-prone than
the "normal" date/time, especially if you copy/paste the latter from
the Git log.

Re: Use of "Action stamps" in commit messages

[Paul Eggert]

On 07/13/2018 02:30 PM, Eli Zaretskii wrote:
> I think generating the RFC3339 time stamps is more error-prone than
> the "normal" date/time, especially if you copy/paste the latter from
> the Git log.

Could we make it easier to generate an action stamp from the commit ID
or from a position in a VC log buffer when editing a later commit
message? The idea is to have something that is easier and more reliable
than the current process, where I manually convert the timestamp format
and time zone. I'm not surprised that others don't want to bother with
doing that.

Re: Use of "Action stamps" in commit messages

[Eric S. Raymond]

Paul Eggert <eggert@cs.ucla.edu>:
> On 07/13/2018 02:30 PM, Eli Zaretskii wrote:
> > I think generating the RFC3339 time stamps is more error-prone than
> > the "normal" date/time, especially if you copy/paste the latter from
> > the Git log.
> 
> Could we make it easier to generate an action stamp from the commit ID
> or from a position in a VC log buffer when editing a later commit
> message? The idea is to have something that is easier and more reliable
> than the current process, where I manually convert the timestamp format
> and time zone. I'm not surprised that others don't want to bother with
> doing that.

We have this tool called "Emacs"....
-- 
		<a href="http://www.catb.org/~esr/">Eric S. Raymond</a>

My work is funded by the Internet Civil Engineering Institute: https://icei.org
Please visit their site and donate: the civilization you save might be your own.

Re: Use of "Action stamps" in commit messages

[Eli Zaretskii]

> Cc: emacs-devel@gnu.org
> From: Paul Eggert <eggert@cs.ucla.edu>
> Date: Fri, 13 Jul 2018 15:10:41 -0500
> 
> Could we make it easier to generate an action stamp from the commit ID
> or from a position in a VC log buffer when editing a later commit
> message?

What UI did you have in mind?  Something like "with point on a Git
SHA1 or the result of 'git describe', invoke a command that will
replace those with an action stamp"?  If so, I think it would be nice
to have that, yes.

While at that: what should we do with SHA1 signatures added
automatically by the likes of "git cherry-pick -x"?  Use -xe and
invoke the above hypothetical command?  Something else?

Re: Use of "Action stamps" in commit messages

[Paul Eggert]

On 07/14/2018 02:08 AM, Eli Zaretskii wrote:
> What UI did you have in mind? Something like "with point on a Git
> SHA1 or the result of 'git describe', invoke a command that will
> replace those with an action stamp"?  If so, I think it would be nice
> to have that, yes.

Something like that, yes. I haven't thought through the design.

> While at that: what should we do with SHA1 signatures added
> automatically by the likes of "git cherry-pick -x"?  Use -xe and
> invoke the above hypothetical command?  Something else?

Sorry, I don't know what -xe is.

Something else that might help would be to have
build-aux/git-hooks/commit-msg check for SHA1 signatures and advise the
committer to use the hypothetical command to resolve them.

Re: Use of "Action stamps" in commit messages

[Eli Zaretskii]

> Cc: esr@thyrsus.com, emacs-devel@gnu.org
> From: Paul Eggert <eggert@cs.ucla.edu>
> Date: Sat, 14 Jul 2018 09:38:45 -0500
> 
> > While at that: what should we do with SHA1 signatures added
> > automatically by the likes of "git cherry-pick -x"?  Use -xe and
> > invoke the above hypothetical command?  Something else?
> 
> Sorry, I don't know what -xe is.

Apologies for being unclear.  I mean "git cherry-pick -xe".

> Something else that might help would be to have
> build-aux/git-hooks/commit-msg check for SHA1 signatures and advise the
> committer to use the hypothetical command to resolve them.

IMO, this would be a nuisance.

Re: Use of "Action stamps" in commit messages

[Andy Moreton]

On Fri 13 Jul 2018, Eric S. Raymond wrote:

> Eli Zaretskii <eliz@gnu.org>:
>> I'm not sure having hyperlinks justifies the trouble of having to
>> concoct those stamps.  In a repository such as we have in Emacs, a
>> time stamp should allow you to find the commit fairly easily, I think.
>
> While this is true, experience leads me to fear a proliferation of
> varying and damaged timestamp formats uttered by people in a hurry.

If people are in a hurry, they should not be comitting changesets in the
first place.

> Only a convention as simple and strong as action stamps has any
> hope of being effective against this sort of drift.

THe linus kenel convention of shortened git sha1 plus commit message
summary line works well in that project. However, they also use
pre-commit review with only maintainers having push access to the repo,
and use automated tooling to ensure that the commit descriptions are in
the correct format. The requirements for pre-commit review is what keeps
everything working.

    AndyM

Re: Use of "Action stamps" in commit messages

[Noam Postavsky]

On 13 July 2018 at 14:15, Eric S. Raymond <esr@thyrsus.com> wrote:

> If you're going to do this, please at least have mercy on future translators
> and use a strict RFC3339 date format the way action stamps do.
>
> I'm against this change because I think in the long term.  Someday Emacs
> will change VCSes again.  On the day, whoever is charged with the move is
> going to curse the perpetrators if he has to deal with a semi-infinite number
> of variant ways of pasting together the data and commit parts of your
> proposed IDs.

I think this thread has somewhat wondered away from what I was
proposing. Currently CONTRIBUTE recommends two ways to refer to
another commit in a commit message:

1. Quoting the summary line.
2. Action stamp

I want to change to just the first:

1. Quoting the summary line

And possibly suggest adding the date before the summary line, as
having a vague idea of how long ago a change was can be helpful. This
is VCS agnostic, so there should be no need for any manipulation when
we move VCS.

> I know of two efforts underway to make cgit and git itself aware of the
> action-stamp format. Have patience.  Soon enough you'll be able to treat
> action stampts as hotlinks that your software will chase for you.

I guess that might be nice, but really, usually having the summary
line gives enough info that I don't even need to chase anything down.
So I consider this better than both hash ids and action stamps. And if
I really do need to look at the referenced commit, then git log --grep
already works. And I think we can safely assume that any other VCS
will support searching for a string in the commit logs, unlike
action-stamp support, which may or may not be supported for any given
VCS.

The action-stamp format is great for the reposurgeon software, but
commit messages are for humans.

Re: Use of "Action stamps" in commit messages

[Brett Gilio]

Noam Postavsky writes:
> The action-stamp format is great for the reposurgeon software, 
> but
> commit messages are for humans.

I second, third, and fourth this. Commit messages are simply a
convenience that I do not think many would feel comfortable doing
without.



-- 
Brett M. Gilio
Free Software Foundation, Member
https://parabola.nu | https://emacs.org