變更日誌的樣式 (GNU 編碼標準)

以下是一些變更日誌條目的簡單範例，首先是標頭行，說明了誰進行了變更以及何時安裝，然後是特定變更的描述。（這些範例取自 Emacs。）請記住，顯示變更日期、作者姓名和電子郵件地址的行僅在單獨的 ChangeLog 檔案中才需要，當變更日誌保存在 VCS 中時則不需要。

2019-08-29  Noam Postavsky  <npostavs@gmail.com>

	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  <eggert@cs.ucla.edu>

	Port to platforms where tputs is in libtinfow

	* configure.ac (tputs_library): Also try tinfow, ncursesw (Bug#33977).

2019-02-08  Eli Zaretskii  <eliz@gnu.org>

	Improve documentation of 'date-to-time' and 'parse-time-string'

	* 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)

如果您提及修改過的函式或變數的名稱，務必完整地命名它們。不要縮寫函式或變數名稱，也不要將它們組合起來。後續的維護者經常會搜尋函式名稱，以找到所有與其相關的變更日誌條目；如果您縮寫名稱，他們在搜尋時將找不到它。

例如，有些人可能會想縮寫函式名稱組，寫成 ‘* register.el ({insert,jump-to}-register)’；這不是一個好主意，因為搜尋 jump-to-register 或 insert-register 將無法找到該條目。

用空白行分隔不相關的變更日誌條目。不要在條目中的個別變更之間放置空白行。當連續的個別變更在同一個檔案中時，您可以省略檔案名稱和星號。

透過用 ‘)’ 而不是 ‘,’ 結束續行，並用 ‘(’ 開啟續行，來斷開函式名稱的長列表。這使得 Emacs 中的高亮度顯示效果更好。以下是一個範例

* src/keyboard.c (menu_bar_items, tool_bar_items)
(Fexecute_extended_command): Deal with 'keymap' property.

將條目新增到 ChangeLog 的最簡單方法是使用 Emacs 命令 M-x add-change-log-entry，或其變體 C-x 4 a (add-change-log-entry-other-window)。這會自動收集已變更的檔案名稱以及已變更的函式或變數，並根據上述慣例格式化變更日誌條目，讓您描述對該函式或變數所做的變更。

當您安裝別人的變更時，請將貢獻者的姓名放在變更日誌條目中，而不是條目的文字中。換句話說，寫成這樣

2002-07-14  John Doe  <jdoe@gnu.org>

        * sewing.c: Make it sew.

2002-07-14  Usual Maintainer  <usual@gnu.org>

        * sewing.c: Make it sew.  Patch by jdoe@gnu.org.

當將別人的變更提交到 VCS 時，請使用 VCS 功能來指定作者。例如，對於 Git，使用 git commit --author=author。

至於日期，應該是您套用變更的日期。（對於 VCS，請使用適當的命令列開關，例如，git commit --date=date。）

現代 VCS 具有套用透過電子郵件發送的變更的命令（例如，Git 具有 git am）；在這種情況下，變更集的作者和建立日期將自動從電子郵件訊息中收集並記錄在儲存庫中。如果修補程式是使用適當的 VCS 命令（例如 git format-patch）準備的，則電子郵件訊息正文也將包含變更集的原始作者，因此重新發送或轉發訊息不會干擾將變更歸於其作者。因此，我們建議您要求貢獻者使用諸如 git format-patch 之類的命令來準備修補程式。

6.8.2 變更日誌的樣式