bug-standards
[Top][All Lists]
Advanced

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

Re: [patch] Allow full explanation in change log for certain changes


From: Karl Berry
Subject: Re: [patch] Allow full explanation in change log for certain changes
Date: Sat, 30 Jun 2012 15:41:29 GMT

    Rationale: We currently urge rationale/why information to be placed
    in the comments, and that should not change.  This change maintains
    that spirit, giving guidance for cases when "comments in code" is
    impossible.

rms finally replied (delay partly due to his laptop being stolen), and
said ok.  I rewrote the ChangeLog entry simply because I failed to find
yours until I'd already committed it.  Oops.  Here's what I just
installed.  I don't think there were any meaningful changes from your
proposal.

karl


2012-06-30  Thien-Thi Nguyen  <address@hidden>
        and Karl Berry  <address@hidden>

        * standards.texi (Change Log Concepts): mention possibility
        of a one-line description describing the overall purpose;
        the full description of changes to media files and others without
        a comment syntax can go in the ChangeLog.

*** standards.texi      1 Jun 2012 17:15:42 -0000       1.217
--- standards.texi      30 Jun 2012 15:35:01 -0000      1.218
***************
*** 3542,3545 ****
--- 3542,3555 ----
  batch of changes that belong together, also known as a @dfn{change
  set}.
+ @cindex title, change log entry
+ @cindex description, change log entry
+ 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.
+ 
+ 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.
  
  The change log file is normally called @file{ChangeLog} and covers an
***************
*** 3553,3570 ****
  @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 log entry.  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, 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.
  
  The easiest way to add an entry to @file{ChangeLog} is with the Emacs
--- 3563,3578 ----
  @kbd{C-x v a} (@code{vc-update-change-log}) does the job.
  
! 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.
! 
! 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.
  
  The easiest way to add an entry to @file{ChangeLog} is with the Emacs



reply via email to

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