[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: New script for generating ChangeLog from Git
|
From: |
John Darrington |
|
Subject: |
Re: New script for generating ChangeLog from Git |
|
Date: |
Mon, 13 Jan 2020 09:16:42 +0100 |
|
User-agent: |
NeoMutt/20170113 (1.7.2) |
In general this seems good to me.
There are a number of typos etc, but you asked not to concentrate on
details.
My only concern is that this is making the standards ever longer,
and we have evidence the the length of these documents is discouraging
new maintainers.
J'
On Tue, Jan 07, 2020 at 06:46:04PM -0500, Richard Stallman wrote:
Would people please check the proposed added text for standards.texi?
Please don't focus mainly on correctness of the details. I
think we can have confidence in Bruno and Eli to check them.
Please focus on the other levels of correctness and good sense.
Please reply to this message when you start working on this?
------- Start of forwarded message -------
Date: Sat, 04 Jan 2020 17:10:09 +0200
Message-Id: <address@hidden>
From: Eli Zaretskii <address@hidden>
To: Bruno Haible <address@hidden>, Richard Stallman <address@hidden>
In-reply-to: <address@hidden> (message from Richard
Stallman on Tue, 24 Dec 2019 21:37:16 -0500)
Subject: Re: [gnu-prog-discuss] Script for generating ChangeLog from Git
This is an attempt to make some progress out of that old and
never-ending discussion.
Below please find changes to standards.texi based on re-reading all
the relevant discussions. I tried to loosen the recommendations and
guidelines about change logs enough to allow the individual
maintainers set up their own policies, but without losing the sight of
the goal, which is to provide detailed, accurate, and useful history
of changes. I hope the new text will be acceptable even to people
with strong views about the matter, like Joseph Myers.
Let me know what you think.
- --- standards.texi 2020-01-04 10:00:45 +0000
+++ standards.texi 2020-01-04 14:55:41 +0000
@@ -3635,7 +3635,76 @@ future will know about the changes that
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.
+history of how the conflicting concepts arose, who they came from, and
+why were the conflicting changes made.
+
+@cinex software forensics, and change logs
+Therefore, change logs should be detailed enough and accurate enough
+to provide the information commonly required for such @dfn{software
+forensics}. Specifically, change logs should make finding answers to
+the following questions easy:
+
+@itemize @bullet
+@item
+What changes affected a particular source file?
+
+@item
+Was a particular source file renamed or moved, and if so, as part of
+what change?
+
+@item
+What changes affected a given function or macro or definition of a
+data structure?
+
+@item
+Was a function (or a macro or the definition of a data structure)
+renamed or moved from another file, and if so, as part of which
+change?
+
+@item
+What changes deleted a function (or macro or data structure)?
+
+@item
+What was the rationale for a given change, and what were its main
+ideas?
+
+@item
+Is there any additional information regarding the change, and if so,
+where can it be found?
+@end itemize
+
+@cindex VCS
+@cindex version control system, for keeping change logs
+Historically, change logs were maintained on specially formatted
+files. Nowadays, projects commonly keep their source files under a
+@dfn{version control system} (@acronym{VCS}), such as Subversion, or
+Git, or Mercurial. If the @acronym{VCS} repository is publicly
+accessible, and changes are committed to it separately (one commit for
+each logical changeset) and record the authors of each change, then
+the information recorded by the @acronym{VCS} can be used to produce
+the change logs out of @acronym{VCS} logs, and to answer the above
+questions by using the suitable @acronym{VCS} commands. (However, the
+@acronym{VCS} log messages still need to provide some supporting
+information, as described below.) Projects that maintain such
+@acronym{VCS} repositories can decide not to maintain separate change
+log files, and instead rely on the @acronym{VCS} to keep the change
+logs.
+
+If you decide not to maintain separate change log files, you should
+still consider providing them in the release tarballs, for the benefit
+of users who'd like to review the change logs without accessing the
+project's @acronym{VCS} repository. Scripts exist that can produce
+@file{ChangeLog} files from the @acronym{VCS} logs; for example, the
+@file{gitlog-to-changelog} script, which is part of Gnulib, can do
+that for Git repositories. In Emacs, the command @kbd{C-x v a}
+(@code{vc-update-change-log}) does the job of incrementally updating a
+@file{ChangeLog} file from the @acronym{VCS} logs.
+
+If separate change log files @emph{are} maintained, they are normally
+called @file{ChangeLog}, and each such file covers an entire
+directory. Each directory can have its own change log file, or a
+directory can use the change log of its parent directory---it's up to
+you.
@menu
* Change Log Concepts::
@@ -3646,10 +3715,10 @@ history of how the conflicting concepts
@end menu
@node Change Log Concepts
- -@subsection Change Log Concepts
+@subsection Change Log Concepts and Conventions
- -@cindex change set
- -@cindex batch of changes
+@cindex change set, in a change log
+@cindex batch of changes, in a change log
You can think of the change log as a conceptual ``undo list'' which
states how earlier versions were different from the current version.
People can see the current version; they don't need the change log to
@@ -3660,25 +3729,28 @@ batch of changes that belong together, a
set}.
@cindex title, change log entry
- -@cindex description, change log entry
- -It is a good idea to start the change log entry with a description
- -of the overall change. This should be as long as needed to give
- -a clear description.
- -
- -Then give a list of names of the entities or definitions that you
- -changed, according to the files they are in, and what was changed
- -in each one. @xref{Style of Change 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.
+@cindex header line, change log entry
+It is a good idea to start the change log entry with a @dfn{header
+line}: a single line that is a complete sentence which summarizes the
+change set. If you keep the change log in a @acronym{VCS}, this
+should be a requirement, as @acronym{VCS} commands that show the
+change log in abbreviated form, such as @kbd{git log --oneline}, treat
+the header line specially. (In a @file{ChangeLog} file, the header
+line follows a line that says who was the author of the change and
+when it was installed.)
- -Instead of using a file named @file{ChangeLog}, you can record the
- -change log information as log entries in 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.
+@cindex description, change log entry
+Follow the change log entry's header line with a description of the
+overall change. This should be as long as needed to give a clear
+description. Pay special attention to aspects of the change set not
+easily gleaned from the diffs or from the names of modified files and
+functions: the overall idea of the change and the need for it, and the
+relations, if any, between changes made to different files/functions.
+If the change or its reasons were discussed on some public forum, such
+as the project's issue tracker or mailing list, it is a good idea to
+summarize the main points of that discussion in the change's
+description, and include a pointer to that discussion or the issue ID
+for those who'd like to read it in full.
The best place to explain how parts of the new code work with other code
is in comments in the code, not in the change log.
@@ -3693,14 +3765,55 @@ tree.'' (Though such a simple reason wo
explanation.)
The best place for other kinds of explanation of the change is in the
- -change log entry.
+change log entry. In particular, comments usually will not say why
+some code was deleted or moved to another place---that belongs to the
+description of the change which did that.
+
+Following the free-text description of the change, it is a good idea
+to give a list of names of the entities or definitions that you
+changed, according to the files they are in, and what was changed in
+each one. @xref{Style of Change Logs}. If a project uses a modern
+@acronym{VCS} to keep the change log information, as described in
+@ref{Change Logs}, explicitly listing the files and functions that
+were changed is not strictly necessary, and in some cases (like
+identical mechanical changes in many places) even tedious. It is up
+to you to decide whether to allow your project's developers to omit
+the list of changed files and functions from the log entries, and
+whether to allow such omissions under some specific conditions.
+However, while making this decision, please consider the following
+benefits of providing the list of changed entities with each change:
+
+@itemize @bullet
+@item
+While modern @acronym{VCS} commands, such as Git's @kbd{git log -L}
+and @kbd{git log -G}, provide powerful means for finding changes that
+affected a certain function or macro or data structure, they can
+sometimes fail. For example, @kbd{git log -L} doesn't support syntax
+of some programming languages out of the box. Mentioning the modified
+functions/macros explicitly allows finding the related changes simply
+and reliably.
+
+@item
+Some @acronym{VCS} commands have difficulties or limitations when
+tracking changes across file moves or renames. Again, if the entities
+are mentioned explicitly, those difficulties can be overcome.
+
+@item
+Users that review changes using the generated @file{ChangeLog} files
+may not have the repository and the @acronym{VCS} commands available
+to them. Naming the modified entities alleviates that problem.
+@end itemize
- -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.
+@noindent
+For these reasons, providing lists of modified files and functions
+with each change makes the change logs more useful, and we therefore
+recommend to include them whenever possible and practical.
+
+It is also possible to generate the lists naming the modified entities
+by running a script. One such script is @file{gitlog_to_changelog.py}
+(written in Python 3); it is used by the @code{glibc} project. Note
+that this currently supports fewer programming languages than the
+manual commands provided by Emacs (@pxref{Style of Change Logs}).
@node Style of Change Logs
@subsection Style of Change Logs
@@ -3709,30 +3822,47 @@ function or variable.
Here are some simple examples of change log entries, starting with the
header line that says who made the change and when it was installed,
followed by descriptions of specific changes. (These examples are
- -drawn from Emacs and GCC.)
+drawn from Emacs.) Keep in mind that the line which shows the date of
+the change and the author's name and email address is needed only in a
+separate @file{ChangeLog} file, not when the change logs are kept in a
+@acronym{VCS}.
@example
- -1998-08-17 Richard Stallman <rms@@gnu.org>
+2019-08-29 Noam Postavsky <address@hidden>
+
+ Handle completely undecoded input in term (Bug#29918)
+
+ * lisp/term.el (term-emulate-terminal): Avoid errors if the whole
+ decoded string is eight-bit characters. Don't attempt to save the
+ string for next iteration in that case.
+ * test/lisp/term-tests.el (term-decode-partial)
+ (term-undecodable-input): New tests.
+
+2019-06-15 Paul Eggert <address@hidden>
+
+ Port to platforms where tputs is in libtinfow
- -* register.el (insert-register): Return nil.
- -(jump-to-register): Likewise.
+ * configure.ac (tputs_library): Also try tinfow, ncursesw (Bug#33977).
- -* sort.el (sort-subr): Return nil.
+2019-02-08 Eli Zaretskii <address@hidden>
- -* tex-mode.el (tex-bibtex-file, tex-file, tex-region):
- -Restart the tex shell if process is gone or stopped.
- -(tex-shell-running): New function.
+ Improve documentation of 'date-to-time' and 'parse-time-string'
- -* expr.c (store_one_arg): Round size up for move_block_to_reg.
- -(expand_call): Round up when emitting USE insns.
- -* stmt.c (assign_parms): Round size up for move_block_from_reg.
+ * doc/lispref/os.texi (Time Parsing): Document
+ 'parse-time-string', and refer to it for the description of
+ the argument of 'date-to-time'.
+
+ * lisp/calendar/time-date.el (date-to-time): Refer in the doc
+ string to 'parse-time-string' for more information about the
+ format of the DATE argument. (Bug#34303)
@end example
- -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.
+If you mention the names of the modified functions or variables, it's
+important to name them 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,jump-to@}-register)};
@@ -3749,10 +3879,18 @@ Break long lists of function names by cl
@samp{(} as in this example:
@example
- -* keyboard.c (menu_bar_items, tool_bar_items)
+* src/keyboard.c (menu_bar_items, tool_bar_items)
(Fexecute_extended_command): Deal with 'keymap' property.
@end example
+The easiest way to add an entry to @file{ChangeLog} is with the Emacs
+command @kbd{M-x add-change-log-entry}, or its variant @kbd{C-x 4 a}
+(@code{add-change-log-entry-other-window}). This automatically
+collects the name of the changed file and the changed function or
+variable, and formats a change log entry according to the conventions
+described above, leaving it up to you to describe the changes you made
+to that function or variable.
+
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:
@@ -3772,7 +3910,18 @@ rather than this:
* sewing.c: Make it sew. Patch by jdoe@@gnu.org.
@end example
+When committing someone else's changes into a @acronym{VCS}, use the
+@acronym{VCS} features to specify the author. For example, with Git,
+use @kbd{git commit --author=@var{author}}.
+
As for the date, that should be the date you applied the change.
+(With a @acronym{VCS}, use the appropriate command-line switches,
+e.g., @kbd{git commit --date=@var{date}}.)
+
+Modern @acronym{VCS} have commands to apply changes sent via email
+(e.g., Git has @kbd{git am}); in that case the author of the changeset
+and the date it was made will be automatically gleaned from the email
+message and recorded in the repository.
@node Simple Changes
@subsection Simple Changes
@@ -3780,6 +3929,15 @@ As for the date, that should be the date
Certain simple kinds of changes don't need much detail in the change
log.
+If the description of the change is short enough, it can serve as its
+own header line:
+
+@example
+2019-08-29 Eli Zaretskii <address@hidden>
+
+ * lisp/simple.el (kill-do-not-save-duplicates): Doc fix. (Bug#36827)
+@end example
+
When you change the calling sequence of a function in a simple fashion,
and you change all the callers of the function to use the new calling
sequence, there is no need to make individual entries for all the
@@ -3795,6 +3953,18 @@ When you change just comments or doc str
entry for the file, without mentioning the functions. Just ``Doc
fixes'' is enough for the change log.
+Similarly, when a lot of simple mechanical changes are done in many
+files. Here's an example of such a change that affects all of the
+files in the repository:
+
+@example
+2019-01-07 Paul Eggert <address@hidden>
+
+ Update copyright year to 2019
+
+ Run 'TZ=UTC0 admin/update-copyright $(git ls-files)'.
+@end example
+
There's no technical need to make change log entries for non-software
files (manuals, help files, media files, etc.). This is because they
are not susceptible to bugs that are hard to understand. To correct
@@ -3803,7 +3973,9 @@ is enough to compare what the file says
However, you should keep change logs for non-software files when the
project gets copyright assignments from its contributors, so as to
- -make the records of authorship more accurate.
+make the records of authorship more accurate. For that reason, we
+recommend to keep change logs for Texinfo sources of your project's
+manuals.
@node Conditional Changes
@subsection Conditional Changes
------- End of forwarded message -------
--
Dr Richard Stallman
Chief GNUisance of the GNU Project (https://gnu.org)
Founder, Free Software Foundation (https://fsf.org)
Internet Hall-of-Famer (https://internethalloffame.org)