[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Circumstances in which ChangeLog format is no longer useful
From: |
Joseph Myers |
Subject: |
Circumstances in which ChangeLog format is no longer useful |
Date: |
Fri, 28 Jul 2017 14:42:18 +0000 |
User-agent: |
Alpine 2.20 (DEB 67 2015-01-07) |
I would like to suggest that there are certain circumstances in which it
is no longer useful to write descriptions of changes in the ChangeLog
format described in the GNU Coding Standards, and in which writing such
descriptions serves to add significant extra work to maintaining a
package, and serves to discourage contributions, without providing any
corresponding benefit. In these circumstances, I would suggest that the
GNU Coding Standards should no longer require such logs to be maintained
in that format or included in releases.
The conditions I propose (with rationale) are:
1. The package has a public version control system.
(Rationale: this ensures people can see what changed, just as with
ChangeLogs, but can see *exactly* what changed rather than just the brief
descriptions.)
2. The version control uses a distributed version control system.
(Rationale: this ensures people can get a complete copy of the history of
what changed, as they can with ChangeLog files in releases.)
3. Commits are made for each logical change, not batched into a commit per
release or per day or other such batching.
(Rationale: this ensures as much separation of logically separate changes
as there would be in a ChangeLog file.)
4. The version control system tracks authors of changes, not just
committers, or is used in a way that tracks authors.
(Rationale: authorship is relevant for copyright purposes.)
5. Commit messages describe the logical "what" changed (but don't
necessarily describe the physical "what" at the level of changes to
individual files and functions).
(Rationale: the logical "what" is useful information at the human level
for understanding the change. Listing individual changed files and
functions both duplicates the information available from the version
control system, and is at the wrong level for understanding the change for
most purposes. It's normal in glibc, for example, for a change to affect
many separate files and named entities in those files, in ways that are
repetitive but not repetitive enough to use e.g. "All callers changed",
and which the ChangeLog format does not provide a good fit to or result in
useful information about the changes not available from version control.)
In my proposal, *existing* ChangeLogs would still need to be kept to the
extent that past commit logs do not meet those requirements, but it would
not be required to maintain such files in future if those requirements are
met, and nor would commit logs need to be convertible automatically to the
ChangeLog format.
Now for how these meet all the purposes of ChangeLog files as described in
the GNU Coding Standards:
Keep a change log to describe all the changes made to program source
files. The purpose of this is so that people investigating bugs in the
future will know about the changes that might have introduced the bug.
Often a new bug can be found by looking at what was recently changed.
More importantly, change logs can help you eliminate conceptual
inconsistencies between different parts of a program, by giving you a
history of how the conflicting concepts arose and who they came from.
All this information is available in version control.
You can think of the change log as a conceptual ``undo list'' which
explains how earlier versions were different from the current version.
People can see the current version; they don't need the change log to
tell them what is in it. What they want from a change log is a clear
explanation of how the earlier version differed. Each @dfn{entry} in
a change log describes either an individual change or the smallest
batch of changes that belong together, also known as a @dfn{change
set}.
All this information is available in version control, provided point 3
above (commits for each logical change) is followed.
For later reference or for summarizing, sometimes it is useful to
start the entry with a one-line description (sometimes called a
@dfn{title}) to describe its overall purpose.
This is standard practice for git commit messages.
In the past, we recommended not mentioning changes in non-software
files (manuals, help files, media files, etc.)@: in change logs.
However, we've been advised that it is a good idea to include them,
for the sake of copyright records.
All files are automatically included in version control logs.
The change log file is normally called @file{ChangeLog} and covers an
entire directory. Each directory can have its own change log, or a
directory can use the change log of its parent directory---it's up to
you.
Another alternative is to record change log information with a version
control system such as RCS or CVS. This can be converted automatically
to a @file{ChangeLog} file using @code{rcs2log}; in Emacs, the command
@kbd{C-x v a} (@code{vc-update-change-log}) does the job.
Because the problem with ChangeLogs, as seen in glibc and elsewhere, is
with needing to write descriptions in a particular format, at a level that
is not useful for human understanding of the changes while not being as
detailed as the exact changes themselves in version control, being able to
generate ChangeLogs from version control using suitably-formatted log
messages does not address the issue.
For changes to code, there's no need to describe the full purpose of
the changes or how they work together. If you think that a change
calls for explanation, you're probably right. Please do explain
it---but please put the full explanation in comments in the code,
where people will see it whenever they see the code. For example,
``New function'' is enough for the change log when you add a function,
because there should be a comment before the function definition to
explain what it does, how to call it, and so on.
For changes to files that do not support a comment syntax (e.g., media
files), it is ok to include the full explanation in the change log file,
after the title and before the list of individual changes.
This is unaffected by describing changes as the logical "what" changed
rather than at the level of all the individual files and functions.
The easiest way to add an entry to @file{ChangeLog} is with the Emacs
command @kbd{M-x add-change-log-entry}. An individual change should
have an asterisk, the name of the changed file, and then in
parentheses the name of the changed functions, variables or whatever,
followed by a colon. Then describe the changes you made to that
function or variable.
This form of description is exactly what's the problem. In the presence
of ubiquitous distributed version control, writing this style of
description is the equivalent of:
/* Add 1 to i. */
i++;
(that is, just repeating the immediately obvious meaning of the history
that everyone can see, and so effectively serving to hide what's actually
interesting about the history at a human level and *should* be described).
It's important to name the changed function or variable in full. Don't
abbreviate function or variable names, and don't combine them.
Subsequent maintainers will often search for a function name to find all
the change log entries that pertain to it; if you abbreviate the name,
they won't find it when they search.
For example, some people are tempted to abbreviate groups of function
names by writing @samp{* register.el (@{insert,address@hidden)};
this is not a good idea, since searching for @code{jump-to-register} or
@code{insert-register} would not find that entry.
People can use "git annotate" and similar tools to identify changes to an
individual function or other section of code, without needing descriptions
to have been written at the level of what changed in that function that
duplicate the version control history showing those changes exactly.
Separate unrelated change log entries with blank lines. Don't put
blank lines between individual changes of an entry. You can omit the
file name and the asterisk when successive individual changes are in
the same file.
This is served by point 3 above.
Break long lists of function names by closing continued lines with
@samp{)}, rather than @samp{,}, and opening the continuation with
@samp{(} as in this example:
This is irrelevant in my proposal, as a formatting detail.
When you install someone else's changes, put the contributor's name in
the change log entry rather than in the text of the entry. In other
words, write this:
This is covered by point 4 above. With git, you would commit with
--author (if there are multiple authors, they'd still need mentioning
explicitly in the commit message).
I don't think the remaining parts of the GNU Coding Standards description
of ChangeLogs really need such annotation, since they are about details of
formatting rather than purpose. But when the formatting description gets
into details of how to describe conditional changes and to describe the
part of an entity changed, that is even more like the "Add 1 to i."
comment, attempting to duplicate in English complicated conditions that
are much more simply read directly from the diffs from version control
whenever someone wants to have that information.
--
Joseph S. Myers
address@hidden
- Circumstances in which ChangeLog format is no longer useful,
Joseph Myers <=
- Re: Circumstances in which ChangeLog format is no longer useful, Alfred M. Szmidt, 2017/07/28
- Re: Circumstances in which ChangeLog format is no longer useful, Joseph Myers, 2017/07/28
- Re: Circumstances in which ChangeLog format is no longer useful, Alfred M. Szmidt, 2017/07/28
- Re: Circumstances in which ChangeLog format is no longer useful, John Darrington, 2017/07/29
- Re: Circumstances in which ChangeLog format is no longer useful, Alfred M. Szmidt, 2017/07/29
- Re: Circumstances in which ChangeLog format is no longer useful, Paul Smith, 2017/07/29
- Re: Circumstances in which ChangeLog format is no longer useful, John Darrington, 2017/07/29
- Re: Circumstances in which ChangeLog format is no longer useful, Rical Jasan, 2017/07/29
- Re: Circumstances in which ChangeLog format is no longer useful, Joseph Myers, 2017/07/31
- Re: Circumstances in which ChangeLog format is no longer useful, Joseph Myers, 2017/07/31