bug-standards
[Top][All Lists]
Advanced

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Standards for generating ChangeLog from git log


From: Richard Stallman
Subject: Standards for generating ChangeLog from git log
Date: Thu, 21 May 2020 23:11:19 -0400

Some of the messages have been cc'd to me, the last one being Monday.
Were there many that I did not get?

I hope that anyone who has more to say will say it withing the coming week.

------- Start of forwarded message -------
Date: Sun, 26 Apr 2020 17:58:28 +0300
Message-Id: <address@hidden>
From: Eli Zaretskii <address@hidden>
To: address@hidden
Cc: address@hidden
In-Reply-To: <address@hidden> (message from Richard
        Stallman on Sat, 25 Apr 2020 23:23:20 -0400)
Subject: Re: [gnu-prog-discuss] Script for generating ChangeLog from Git

> From: Richard Stallman <address@hidden>
> Cc: address@hidden
> Date: Sat, 25 Apr 2020 23:23:20 -0400
> 
>   >   For example, when there is a change in the header part of a function
>   >   definition, the heading of the diff hunk as shown in the VCS log
>   >   commands will name the wrong function as being modified (usually,
>   >   the function defined before the one being modified), so using those
>   >   diffs to glean the names of the modified functions will produce
>   >   inaccurate results.
> 
>   > This should go before the reference to gitlog_to_changelog.py script.
> 
> This will do the job.  So please proceed.

Ok, so here's the complete patch, including that change:

=== modified file 'standards.texi'
- --- standards.texi    2020-01-04 10:00:45 +0000
+++ standards.texi      2020-04-26 14:56:33 +0000
@@ -3,7 +3,7 @@
 @setfilename standards.info
 @settitle GNU Coding Standards
 @c This date is automagically updated when you save this file:
- -@set lastupdate November 17, 2019
+@set lastupdate April 26, 2020
 @c %**end of header
 
 @dircategory GNU organization
@@ -28,8 +28,8 @@ The GNU coding standards, last updated @
 
 Copyright @copyright{} 1992, 1993, 1994, 1995, 1996, 1997, 1998, 1999,
 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010,
- -2011, 2012, 2013, 2014, 2015, 2016, 2017, 2018, 2019 Free Software
- -Foundation, Inc.
+2011, 2012, 2013, 2014, 2015, 2016, 2017, 2018, 2019, 2020 Free
+Software Foundation, Inc.
 
 Permission is granted to copy, distribute and/or modify this document
 under the terms of the GNU Free Documentation License, Version 1.3 or
@@ -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,71 @@ 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
+Generation of useful @file{ChangeLog} files from @acronym{VCS} logs
+becomes more difficult if the change log entries don't list the
+modified functions/macros, because @acronym{VCS} commands cannot
+reliably reproduce their names from the commit information alone.  For
+example, when there is a change in the header part of a function
+definition, the heading of the diff hunk as shown in the VCS log
+commands will name the wrong function as being modified (usually, the
+function defined before the one being modified), so using those diffs
+to glean the names of the modified functions will produce inaccurate
+results.  You will need to use specialized scripts, such as
+@file{gitlog_to_changelog.py}, mentioned below, to solve these
+difficulties, and make sure it supports the source languages used by
+your project.
+
+@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 (and thus might
+make @file{ChangeLog} files unnecessary if you have the repository
+available), 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 +3838,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 +3895,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 +3926,24 @@ 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.  If the patches are prepared
+with suitable @acronym{VCS} commands, such as @kbd{git format-patch},
+the email message body will also have the original author of the
+changeset, so resending or forwarding the message will not interfere
+with attributing the changes to their author.  Thus, we recommend that
+you request your contributors to use commands such as @kbd{git
+format-patch} to prepare the patches.
 
 @node Simple Changes
 @subsection Simple Changes
@@ -3780,6 +3951,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 +3975,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 +3995,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)




reply via email to

[Prev in Thread] Current Thread [Next in Thread]