bug#20328: outdated CONTRIBUTE info re ChangeLogs

bug#20328: outdated CONTRIBUTE info re ChangeLogs

[Glenn Morris]

Package: emacs
Version: 25.0.50
Severity: minor

CONTRIBUTE contains outdated information re ChangeLogs.
Someone should review it and update it.

Random hits (almost every instance related to "ChangeLog" seems wrong to me):

  If committing changes written by someone else, make the ChangeLog
  entry in their name, not yours.

  [...]
  It is tempting to relax this rule for commit messages, since they
  are somewhat transient.

  [...]
  In ChangeLog entries, there is no standard or recommended way to
  identify revisions.

  [...]
  There is no need to make separate ChangeLog entries for files such
  as NEWS, MAINTAINERS...

etc, etc, etc

bug#20328: outdated CONTRIBUTE info re ChangeLogs

[Dmitry Gutov]

On 04/14/2015 09:25 AM, Glenn Morris wrote:

> CONTRIBUTE contains outdated information re ChangeLogs.
> Someone should review it and update it.

I don't know if they're all actually incorrect. Based on an non-obvious 
distinction - yes.

Since a commit message contains a summary, maybe a few headers, and a 
ChangeLog entry, it's fair to describe what a "ChangeLog entry" should 
contain.

> Random hits (almost every instance related to "ChangeLog" seems wrong to me):
>
>    If committing changes written by someone else, make the ChangeLog
>    entry in their name, not yours.

Right, there's no separate name line in the ChangeLog entries inside 
commit messages. Updated.

>    [...]
>    It is tempting to relax this rule for commit messages, since they
>    are somewhat transient.

This one actually seemed outdated. Removed.

>    [...]
>    In ChangeLog entries, there is no standard or recommended way to
>    identify revisions.

This still applies. Even though it could say "in commit messages", this 
also emphasized the fact that the same non-sandardized references will 
appear in the ChangeLog file.

>    [...]
>    There is no need to make separate ChangeLog entries for files such
>    as NEWS, MAINTAINERS...

Still true, and I'm not sure how to rephrase this to refer to commit 
messages.

bug#20328: outdated CONTRIBUTE info re ChangeLogs

[Glenn Morris]

Dmitry Gutov wrote:

> Since a commit message contains a summary, maybe a few headers, and a
> ChangeLog entry, it's fair to describe what a "ChangeLog entry" should
> contain.

IMO the file should be rewritten to explain that commit logs are to be
written in the style of ChangeLogs.

>>    In ChangeLog entries, there is no standard or recommended way to
>>    identify revisions.
>
> This still applies. Even though it could say "in commit messages",
> this also emphasized the fact that the same non-sandardized references
> will appear in the ChangeLog file.

s/could/should.

I guess we are supposed to use those silly "action stamps", but
understandably no-one does. I'm sure people are going to keep using
hashes in commit logs, which will be meaningless in the generated C'log.

>>    There is no need to make separate ChangeLog entries for files such
>>    as NEWS, MAINTAINERS...
>
> Still true, and I'm not sure how to rephrase this to refer to commit
> messages.

If they are in a commit all of their own, you can use the "; " prefix to
omit that entire commit log entry from the generated C'log.

If they are mixed in with other changes, then IIUC there is nothing you
can do. I asked for such a feature (to exclude specific lines of a
commit log), but I don't think it exists.

It would be better if the generate script simply always omitted such
files from the C'log, since they are never interesting.

bug#20328: outdated CONTRIBUTE info re ChangeLogs

[Dmitry Gutov]

On 04/15/2015 07:52 PM, Glenn Morris wrote:

> IMO the file should be rewritten to explain that commit logs are to be
> written in the style of ChangeLogs.

Updated, please take a look.

>> This still applies. Even though it could say "in commit messages",
>> this also emphasized the fact that the same non-sandardized references
>> will appear in the ChangeLog file.
>
> s/could/should.

I'd prefer not to touch this part until the following is resolved.

> I guess we are supposed to use those silly "action stamps", but
> understandably no-one does. I'm sure people are going to keep using
> hashes in commit logs, which will be meaningless in the generated C'log.

Agreed: it's a nuisance. And since it relatively trivial to convert 
commit hashes to the action stamps or whatever when generating 
ChangeLogs, it makes sense to use hashes in the commit messages. Maybe 
prefixed with "git:", if someone is worried about ambiguity.

> If they are in a commit all of their own, you can use the "; " prefix to
> omit that entire commit log entry from the generated C'log.

I think it's also improved now.