* bug#20328: outdated CONTRIBUTE info re ChangeLogs
@ 2015-04-14 6:25 Glenn Morris
2015-04-14 23:26 ` Dmitry Gutov
0 siblings, 1 reply; 4+ messages in thread
From: Glenn Morris @ 2015-04-14 6:25 UTC (permalink / raw)
To: 20328
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
^ permalink raw reply [flat|nested] 4+ messages in thread
* bug#20328: outdated CONTRIBUTE info re ChangeLogs
2015-04-14 6:25 bug#20328: outdated CONTRIBUTE info re ChangeLogs Glenn Morris
@ 2015-04-14 23:26 ` Dmitry Gutov
2015-04-15 16:52 ` Glenn Morris
0 siblings, 1 reply; 4+ messages in thread
From: Dmitry Gutov @ 2015-04-14 23:26 UTC (permalink / raw)
To: Glenn Morris, 20328
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.
^ permalink raw reply [flat|nested] 4+ messages in thread
* bug#20328: outdated CONTRIBUTE info re ChangeLogs
2015-04-14 23:26 ` Dmitry Gutov
@ 2015-04-15 16:52 ` Glenn Morris
2015-04-16 14:54 ` Dmitry Gutov
0 siblings, 1 reply; 4+ messages in thread
From: Glenn Morris @ 2015-04-15 16:52 UTC (permalink / raw)
To: Dmitry Gutov; +Cc: 20328
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.
^ permalink raw reply [flat|nested] 4+ messages in thread
* bug#20328: outdated CONTRIBUTE info re ChangeLogs
2015-04-15 16:52 ` Glenn Morris
@ 2015-04-16 14:54 ` Dmitry Gutov
0 siblings, 0 replies; 4+ messages in thread
From: Dmitry Gutov @ 2015-04-16 14:54 UTC (permalink / raw)
To: Glenn Morris; +Cc: 20328
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.
^ permalink raw reply [flat|nested] 4+ messages in thread
end of thread, other threads:[~2015-04-16 14:54 UTC | newest]
Thread overview: 4+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2015-04-14 6:25 bug#20328: outdated CONTRIBUTE info re ChangeLogs Glenn Morris
2015-04-14 23:26 ` Dmitry Gutov
2015-04-15 16:52 ` Glenn Morris
2015-04-16 14:54 ` Dmitry Gutov
Code repositories for project(s) associated with this external index
https://git.savannah.gnu.org/cgit/emacs.git
https://git.savannah.gnu.org/cgit/emacs/org-mode.git
This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.