bug-standards
[Top][All Lists]
Advanced

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

Re: changelog format


From: Thien-Thi Nguyen
Subject: Re: changelog format
Date: Tue, 17 Jan 2012 17:04:08 +0100
User-agent: Gnus/5.13 (Gnus v5.13) Emacs/24.0.92 (gnu/linux)

() Stefano Lattarini <address@hidden>
() Tue, 17 Jan 2012 15:05:54 +0100

   > I agree that such conveniences are very compelling.  My fear
   > is that people would use VCS commit identifiers exclusively;

   Honestly I've been guilty of doing so for quite a long time now (and should
   get rid of this bad habit ASAP).  But my (or others?) laziness/sloppiness is
   IMHO no excuse to give in incorrect advice in the GCS.

   > saying "in addition to" is not strong enough.  Any other ideas?
   >
   Maybe we could provide a "blessed" script that the developer could use in 
lieu
   of "git describe" (or similar commands for other VCS) to get a GCS-conforming
   string referring to a past commit.  The idea is that, instead of doing 
something
   like this:

     $ git describe c592a00f
     v8.14-91-gc592a00

   the developer could do something like this:

     $ gnu-vcs-describe c592a00f
     v8.14-91-c592a00 (2011-12-08, "ls: be responsive to interrupts ...")

   WDYT?

Sounds fine, but i don't really want to think about implementation
details, especially Git-specific ones, though undoubtedly i would/will
benefit from them.  (Though i hugely favor Git personally, i like RCS,
too, and am trying to do this standards.texi munging w/ a VCS-agnostic
mindset.)

Anyway, i've reworded that part a bit, leaving a placeholder for
gnu-vcs-fu (but commented out).  We can address this later, no?

   >   2011-12-08  Jim Meyering  <address@hidden>

   Yes.

OK, thanks for confirming.

   > (Meta-comment: This extra step shows
   > how generated ChangeLog files are inconvenient to casual readers.)

   How so?  Note that I've copied & pasted the above from the git
   output, not from the corresponding generated ChangeLog.

Well, i didn't have coreutils repo (or tarballs) locally, so i had to
clone it and do "git log", to find that information.

   > I note that there is more than one paragraph, so i guess i'll change
   > the "short paragraph" to "paragraph(s)".
   >
   +1

OK.  Attached is the latest diff.  In addition to the above changes, i
moved the examples to their own node, refilling the one from coreutils
slightly.  I also used @verbatim, but am not sure if that's cool or not.

________________________________________________
*** a/doc/standards.texi
--- b/doc/standards.texi
***************
*** 3,9 ****
  @setfilename standards.info
  @settitle GNU Coding Standards
  @c This date is automagically updated when you save this file:
! @set lastupdate December 10, 2011
  @c %**end of header

  @dircategory GNU organization
--- 3,9 ----
  @setfilename standards.info
  @settitle GNU Coding Standards
  @c This date is automagically updated when you save this file:
! @set lastupdate gennaio 17, 2012
  @c %**end of header

  @dircategory GNU organization
***************
*** 3495,3500 ****
--- 3495,3501 ----
  * Simple Changes::
  * Conditional Changes::
  * Indicating the Part Changed::
+ * Change Log Examples::
  @end menu

  @node Change Log Concepts
***************
*** 3516,3531 ****
  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.

- There's no need to describe the full purpose of the changes or how
- they work together.  However, sometimes it is useful to write one line
- to describe the overall purpose of a change or a batch of changes.  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.
-
  In the past, we recommended not mentioning changes in non-software
  files (manuals, help files, etc.) in change logs.  However, we've been
  advised that it is a good idea to include them, for the sake of
--- 3517,3522 ----
***************
*** 3536,3541 ****
--- 3527,3559 ----
  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.
+ Each group of related entries should have a @dfn{title}, a one line
+ description or summary of the change, and optionally zero or more
+ paragraphs to:
+
+ @table @asis
+ @item describe motivation
+ A change conceptually has three parts: before, why and after.
+ ``Before'' and ``after'' are captured in the version control system,
+ but where to capture ``why'' depends on what changed.  When source
+ code changes in a small number of files, the best place for ``why'' is
+ in the comments.  For other circumstances---many files or changes to
+ files that do not support a comment syntax---the change log is the
+ best place.
+
+ @item link to external resources
+ This includes bug report or mailing list URLs.
+
+ @item link to another entry
+ This is useful when a change is a fix or continuation
+ of a previous change.
+
+ @item give credit
+ It is courteous to acknowledge the help of others.  Although such
+ information may be available indirectly through a URL, including it
+ in the change log fosters community spirit and makes it more
+ self-contained.
+ @end table

  @node Style of Change Logs
  @subsection Style of Change Logs
***************
*** 3544,3550 ****
  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.)

  @example
  1998-08-17  Richard Stallman  <rms@@gnu.org>
--- 3562,3568 ----
  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, from back when the title was optional.)

  @example
  1998-08-17  Richard Stallman  <rms@@gnu.org>
***************
*** 3609,3614 ****
--- 3627,3653 ----

  As for the date, that should be the date you applied the change.

+ In the paragraph(s), URLs should have angle braces and (non-patch)
+ credits may optionally exclude the contributor's email address.
+ (A patch should be handled as described above.)
+
+ A link to another entry should be expressed as a date and an
+ optional title, if the date is insufficient to uniquely identify
+ a particular change.  We recommend this over using @strong{only}
+ a VCS commit identifier primarily to keep the change log
+ self-contained, and secondarily to avoid lossage should the
+ project change VCS in the future.
+ @c FIXME: Maybe a reference to gnu-vcs-fu is better.
+ @c For generated change log files, you can use [gnu-vcs-fu ref] to [DTRT].
+
+ Whether or not to add extra blank lines around the paragraph(s) is
+ up to you.  If so, each group of changes should have its own heading.
+ (In Emacs, set @code{add-log-always-start-new-record} to @code{t}.)
+
+ Likewise, what constitutes the title is up to you.
+ We note here only that many projects use the form:
+ @var{topic}[, @address@hidden: @var{description}.
+
  @node Simple Changes
  @subsection Simple Changes

***************
*** 3698,3703 ****
--- 3737,3787 ----
  user-specified option string is empty.
  @end example

+ @node Change Log Examples
+ @subsection Change Log Examples
+
+ Here are two slightly-edited examples from coreutils and Serveez,
+ respectively.
+
+ @c Use @verbatim to avoid ugly over-indentation w/ @example.
+ @verbatim
+ 2011-12-08  Jim Meyering  <address@hidden>
+
+         ls: be responsive to interrupts when color-listing large dirs
+
+         This change fixes coreutils bug#10243.
+         Reported by Arkadiusz Miskiewicz.
+
+         Starting with commit adc30a83, when using --color, ls
+         inhibited interrupts to avoid corrupting the state of an
+         output terminal.  However, for very large directories, that
+         inhibition rendered ls uninterruptible for too long,
+         including a potentially long period even before any output
+         is generated.
+
+         * src/ls.c: Two phases of processing are time-consuming
+         enough that they can provoke this: the readdir loop and the
+         printing loop.  The printing was supposed to be covered by
+         a call to process_signals in
+         (print_name_with_quoting): ... but that call was mistakenly
+         guarded by a condition that might be false for many or even
+         all files being processed.  Call process_signals
+         unconditionally.
+         (print_dir): Also call process_signals in the readdir loop.
+         * NEWS (Bug fixes): Mention it.
+
+ 2011-10-26  Thien-Thi Nguyen  <address@hidden>
+
+         [build int] Fix bug: Move codec glue Automake conds later.
+
+         Regression introduced 2011-07-15, "Use
+         Automake conditionals to gate codec glue".
+         Reported by Mike Gran.
+
+         * configure.ac (WITH_ZLIB, WITH_BZLIB): Move into section
+         "write it out", which is after "checks for header files".
+ @end verbatim
+

  @node Man Pages
  @section Man Pages

reply via email to

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