wiki:ChangeLogDetails

Jeremy asked for suggestions about how to do change logs, and Jinmei replied with this proposal. We have provisionally adopted it.

Example

This is an example changelog entry:

214.	[func]*		vorner
	Zone manager no longer thinks it is secondary master for
	all zones in the database. They are listed in
	Zonemgr/secondary_zones configuration variable (in the form
	[{"name": "example.com", "class": "IN"}]).
	(Trac #670, git 7c1e4d5e1e28e556b1d10a8df8d9486971a3f052)

LEGEND

[bug] general bug fix. This is generally a backward compatible change, unless it's deemed to be impossible or very hard to keep compatibility to fix the bug.

[build] compilation and installation infrastructure change.

[doc] update to documentation. This shouldn't change run time behavior.

[func] new feature. In some cases this may be a backward incompatible change, which would require a bump of major version.

[security] security hole fix. This is no different than a general bug fix except that it will be handled as confidential and will cause security patch releases.

*: Backward incompatible or operational change.

Explanation

The goal of the change log is mostly for helping the end-user recognize new features or behavioral changes. Also it may be useful for marketing and publicity purposes.

Any interesting change should be briefly described. All user noticable changes must be described. If detailed, pointing to specific documentation is acceptable. Write the description to be useful for end-user of developer APIs or functionality. If it is a fix for recent code that is un-released (no shipped tarball), then a new changelog entry may not be needed -- maybe just extend previous entry if appropriate. (Note that more developer useful information would be in the git commit messages.)

Entries are numbered. The numbers are flush left. The numbers decrease -- the latest entry with greatest number is at the top of document.

After the entry number, a keyword type within [brackets] is used to describe the change. These are listed in the legend above. Use your best judgement or ask in jabber if unsure.

Following the keyword type, the username of the committer is shown. This is separated with two tabs. In some cases, there may be multiple committers, delimited with comma and space. If the patch or code was provided from outside of team, then they should be acknowledged by name in the description.

Changes that have an operational change or interface change that is not compatible should be flagged with an asterisk after the keyword.

The description of the entry should be grammatically correct. It is indented with a single tab.

The corresponding Trac # and git hash (revision) is included. The git hash may correspond to a merge. There may be multiple Trac numbers and git hashes per a single change entry.

This is similar to BIND 9's CHANGES entry, but is different in the following points:

  • it has the corresponding git hash. this may not always be feasible, so I'd consider this optional.
  • it shows the developer committing to the change. I'm not necessarily pushing this style, but thought it might be better in that we give clear credit to the contribution, especially because BIND 10 is (and will be hopefully) multi organization effort, perhaps also with individual committers in future.
  • it shows a brief legend of change "categories".

The description of the change is not very detailed as the DHCP-style example. In fact, the DHCP ones are "release notes", rather than a mere "log of changes". I tend to agree that it's nice to provide a more readable release note containing details of major changes (BIND 9's release notes are not very good in this sense), but I think it makes sense to have a relatively concise list of changes. So, in the above proposal I tried to avoid being too detailed.

I know the overhead may become an issue if we try to provide both this style of change logs and more detailed release notes. If it turns out to be the case we may consider consolidating those.

About this Document

Created by Shane 2010-06-02
Review scheduled 2011-07-08

Based on an e-mail proposal from Jinmei: https://lists.isc.org/pipermail/bind10-dev/2010-May/000851.html

Last modified 7 years ago Last modified on Apr 8, 2011, 5:19:24 PM