[Top][All Lists]
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
FYI: changelog formatting notes [libtool--devo--1.0--patch-1]
From: |
Gary V. Vaughan |
Subject: |
FYI: changelog formatting notes [libtool--devo--1.0--patch-1] |
Date: |
Sat, 8 Jan 2005 19:05:37 +0000 (GMT) |
User-agent: |
mailnotify/0.6 |
-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1
Applied to HEAD.
* looking for address@hidden/libtool--devo--1.0--base-0 to compare with
* comparing to address@hidden/libtool--devo--1.0--base-0
M ChangeLog
M HACKING
* modified files
Index: Changelog
from Gary V. Vaughan <address@hidden>
* ChangeLog: Reformatting.
* HACKING: Fix section numbering.
(Editing 'ChangeLog'): New notes on ChangeLog entry format.
--- orig/HACKING
+++ mod/HACKING
@@ -48,14 +48,14 @@
* Changes other than bug fixes must be mentioned in NEWS
-2. Test Suite
+3. Test Suite
=============
* Use "make check" liberally, on as many platforms as you can. Use as
many compilers and linkers you can.
-3. Naming
+4. Naming
=========
* We've adopted the convention that exported Autoconf macros should be
@@ -71,7 +71,102 @@
with the `_lt_' macro namespace).
-4. Editing `.am' Files
+5. Editing 'ChangeLog'
+======================
+
+* When in doubt, check that emacs can syntax-color properly in
+ change-log-mode. And preferably use emacs 'C-x 4 a'
+ (add-change-log-entry-other-window) to open ChangeLog with an
+ appropriate new template.
+
+* If this change is by a different author, or on a different date to the
+ last entry start a new entry at the top of the file with the format
+ (note two spaces between each field):
+
+yyyy-mm-dd Name of Author <address@hidden>
+
+* 'Name of Author' is the name of the person who made the change being
+ documented, or if that person didn't supply a ChangeLog, the author
+ of the ChangeLog entry. If more than one person collaborated on the
+ change, additional authors can be listed on subsequent lines, thus:
+
+yyyy-mm-dd Name of Main Author <address@hidden>,
+ Name of Contributor <address@hidden>
+
+* Preferably the next part should be a description of the overall
+ purpose of the change, separated from the header by a blank line,
+ indented by 1 tab, and filled at column 72. The last character of the
+ description should be a colon, :.
+
+* If the author of the change is different from the author of the
+ ChangeLog, then the change outhor should be credited, separated from
+ the previous field by a blank line and indented by 1 tab (note, only
+ 1 space between fields here):
+
+ From Author of Actual Change <address@hidden>:
+
+* Changes to each file come next. Each new file starts on a new line,
+ indented by 1 tab and starting with an asterisk and a space. Multiple
+ files can be listed here relative to $top_srcdir, and comma separated.
+ Names of functions (or sections as appropriate) to which the change
+ applies should be named inside parentheses and comma separated. If
+ this goes beyond column 72, then parens should be closed and re-opened
+ on the next line:
+
+ * file, another/file, test/testcases/foo.test (func_foo)
+ (func_bar, func_baz): Description of changes.
+
+* If the change does not apply to particular functions (or sections),
+ the section list can be omitted:
+
+ * file, another/file, test/testcases/foo.test: General changes.
+
+* If the changes are particular to certain architectures, they should be
+ listed after the functions in square brackets:
+
+ * file, another/file (func_foo) [linux, solaris]: Description of
+ changes.
+
+* Subsequent changes in other files that are related to the same overall
+ enhancement or bugfix should be listed concurrently, without blank
+ lines. Always start a fresh line for a new file:
+
+ * file, another/file (func_foo) [linux, solaris]: Description of
+ changes.
+ * doc/foo.texi (Invoking Foo): Document.
+ * NEWS: Updated.
+
+* If the change is in response to a problem reported by someone other
+ than the author, then credit them at the end of the description with:
+
+ Reported by Reporter Name <address@hidden>.
+
+* See the GNU Coding Standards document for more details on ChangeLog
+ formatting.
+
+
+2005-01-08 Gary V. Vaughan <address@hidden>,
+ Peter O'Gorman <address@hidden>
+
+ This is the overall description of the purpose of this change
+ and any useful background for a model ChangeLog entry:
+
+ From Ralf Wildenhues <address@hidden>:
+ * HACKING: Updated copyright. This isn't attached to a
+ particular section of the file, so it comes first.
+ (Editing 'ChangeLog'): New section. This applies to the same
+ file, but since it applies to a particular section it starts on
+ a new line.
+ (Introduction, Maintenance Notes, Test Suite, Naming)
+ (Editing '.am' Files): If I had changed all these sections in
+ the same way, I can list them like this, being careful to close
+ and reopen the parentheses when starting a new line. The colon
+ only comes after the last section before this description.
+ * NEWS: Updated.
+ Reported by Bob Friesenhahn <address@hidden>.
+
+
+6. Editing `.am' Files
======================
* Always use $(...) and not ${...}
@@ -89,7 +184,7 @@
of the loop itself should print each "important" command it runs.
-5. Editing `.m4sh' Files
+7. Editing `.m4sh' Files
========================
* Use shell functions, but be careful not to assume local scope for
@@ -110,7 +205,7 @@
functions should begin indented by 4 spaces.
-6. Abstraction layers in libltdl
+8. Abstraction layers in libltdl
================================
* The libltdl API uses a layered approach to differentiate internal and
@@ -194,7 +289,7 @@
lt__private.h
-7. Release Procedure
+9. Release Procedure
====================
* If you are a libtool maintainer, but have not yet registered your
@@ -281,8 +376,8 @@
-7. Alpha release note template
-==============================
+10. Alpha release note template
+===============================
To: address@hidden, address@hidden
Subject: GNU Libtool @VERSION@ released (alpha release).
@@ -354,8 +449,8 @@
-8. Full release note template
-=============================
+11. Full release note template
+==============================
To: address@hidden
Cc: address@hidden, address@hidden
@@ -436,7 +531,7 @@
--
-Copyright (C) 2004 Free Software Foundation, Inc.
+Copyright (C) 2004, 2005 Free Software Foundation, Inc.
The canonical source of this file is maintained with the
GNU Libtool package. Report bugs to address@hidden
- --
Gary V. Vaughan ())_. address@hidden,gnu.org}
Research Scientist ( '/ http://tkd.kicks-ass.net
GNU Hacker / )= http://www.gnu.org/software/libtool
Technical Author `(_~)_ http://sources.redhat.com/autobook
_________________________________________________________
This patch notification generated by tlaapply version 0.9
http://tkd.kicks-ass.net/arch/address@hidden/cvs-utils--tla--1.0
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.2.4 (Darwin)
iD8DBQFB4C8BFRMICSmD1gYRAvyHAKCIu+RjJZ0aDvK64+5hlNOd9iT6qQCgw6qj
pn3CStr4rnmcXF+hmspflY4=
=VZq8
-----END PGP SIGNATURE-----
- FYI: changelog formatting notes [libtool--devo--1.0--patch-1],
Gary V. Vaughan <=