Re: [PATCH 2/2] gitlog-to-changelog: support 'tiny change' commits.

[Gary V. Vaughan]

Ping Karl...

Depending on your thoughts, I will resubmit this patch series for gnulib
rather than keeping the patches solely in Libtool's tree.

On 1 Nov 2011, at 20:56, Gary V. Vaughan wrote:
> On 1 Nov 2011, at 20:13, Jim Meyering wrote:
>> Gary V. Vaughan wrote:
>>> 
>>> diff --git a/ChangeLog b/ChangeLog
>>> index f370be6..d59d9f9 100644
>>> --- a/ChangeLog
>>> +++ b/ChangeLog
>>> @@ -1,5 +1,14 @@
>>> 2011-11-01  Gary V. Vaughan  <address@hidden>
>>> 
>>> +   gitlog-to-changelog: support `tiny change' commits.
>>> +   The FSF insist that all non-trivial patches to its projects are
>> 
>> Even if somewhere you've felt "insistence" on this issue,
>> let's just write "request":
>> 
>> s/insist/request/
>> 
>> s/are/be/ (both above and below)
>> 
>>> +   accompanied by appropriate paperwork, or that any patches that are
>>> +   applied without that paperwork are marked as such in the
>>> +   ChangeLog.
>>> +   * gitlog-to-changelog: Convert `Copyright-paperwork-required: No'
>> 
>> I find that rather long, and have a slight preference
>> to avoid an always-negative setting.
> 
> Sure, I cribbed this from the boilerplate email that Ralf (Wildenhues) sends
> off list to submitters of large patches that we'd like to commit, but which
> are too large to be considered trivial enough to use without paperwork.
> 
>> Did you consider "Tiny-change: Yes"
>> or even simply "/^Tiny[- ]change\b/",
> 
> I did consider, but the whole Tiny Change terminology seems anachronistic to
> me.  Although we have long settled on the unfortunate convention of annotating
> ChangeLog entries with "(tiny change)" whenever a patch is considered by the
> committer to be trivial enough not to require an exchange of copyright 
> paperwork,
> I think it is clearer and more sensible to state that directly than be forever
> explaining to patch submitters that we're not belittling their contribution, 
> but
> merely noting that we don't require them to file a copyright disclaimer.
> 
> I chose the negative version to optimise for frequency.  I would hate to have
> to add 'Copyright-paperwork-on-file: Yes' to almost every patch.  I guess I'd
> be happy with 'Copyright-paperwork-not-required: .*$', if it's just the 'No'
> that you dislike... although it feels a lot more awkward to write
> 'xxx-not-required: Yes' than a simple 'xxx-required: No'.
> 
>> so that "Tiny change by ..." will be recognized.
> 
> I actually dislike the 'Tiny change' misnomer, and would love to take this
> opportunity to choose a more descriptive and clear annotation for git logs,
> while still respecting the established ChangeLog standards in dist tarballs.
> 
>> Now that I've thought about it a little more, ...
>> 
>> Actually, I question whether establishing such a convention.
>> and going to this trouble is worthwhile, since the size of the
>> change is already known, via the associated patch.
> 
> This is a confusion brought about by the 'Tiny change' misnomer I think.  If
> it were a simple matter of counting lines, then you would be entirely correct
> of course, but what about a refactoring that moves code around considerably
> and generates a huge patch, potentially with a large difference between number
> of lines added vs number of lines removed, even though no new code is added?
> That would certainly qualify for 'Copyright-paperwork-required: No'/'tiny 
> change'.
> 
>> The notation requirement made more sense back each ChangeLog entry
>> was not tied to the associated patch.
> 
> Before modern VCS you mean? That's before my time then... even CVS still ties
> the ChangeLog to the patch does it not?  Or do you mean in a dist tarball, in
> which case git history is not supplied, so there is no tie there either, which
> is why we still distribute ChangeLogs, I think...
> 
>> Authorship matters a lot more than marking a change
>> that is obviously small by some measure as a "(tiny change)".
> 
> Agreed.
> 
> However, Libtool has made considerable effort to keep track of assignments
> and (tiny change) annotations, so at the very least we'll need to keep this or
> something similar in gnulib-local patches before moving to generating 
> ChangeLog
> from git logs at distribution time.  This patch doesn't enforce any 
> requirement
> to set annotations in git log messages, but provides the means to do so for
> the projects that want or need it without local patching.  It would be nicer
> for those projects to centralise the annotation in gnulib, than to each 
> research
> and invent their own mechanism (as I have essentially just done for Libtool).
> 
> The other thing I considered, which is not necessary for Libtool (although we
> would use it over rolling our own if gnulib prefers this route), is to use
> git notes to add the metadata to each commit.  This would allow us to go back
> through history and add notes as necessary that gitlog-to-changelog would
> generate a full ChangeLog (without loss of multiple authors and tiny changes)
> right back to the start of the project, without messing up the SHA1 sums on
> each node in the changeset tree.  In some ways that is more appealing, but I
> worry that the notes might get lost in merge, or forged somehow since they
> are essentially out-of-band.  Putting the annotations directly into the git
> commit message avoids those worries, at the expense of only being applicable
> moving forwards in time from when they are adopted.
> 
>> Let's see what Karl thinks.
> 
> Ack.

Cheers,
-- 
Gary V. Vaughan (gary AT gnu DOT org)