SUSE Package Conventions/Changelogs

From openSUSE

11. Changelogs

This section describes the openSUSE policy for RPM Changelogs. The original Changelogs comming with the original source are not affected by this policy.

In general: Remember that not even a "well informed developer" but also a "normal enduser with some technical skills" should read and understand a RPM-Changelog - even in one or two years and should be able to reconstruct/revert to the previous specfile (except deleted patches).

Changelog entries have to be in chronological order. No fixes of previous changelog entries are allowed if a package is "checked in" to autobuild.

11.1 Bugnumbers in changelog

During maintenance of a distribution, every change has to be marked with the correct bugnumber. Normally this has to be an number from https://bugzilla.novell.com/. Adding an entry with bugzilla number to the changelog should result in a short description of the bug-summary and the bugnumber. For example:

- Removed invalid desktop Category "Application" (bnc#254654).
- Symlink icon to pixmaps dir (bnc#152108)
- Added gnome-ui-properties to control-center (bnc#118960#c11).

To avoid confusion and double burden, referencing to other bugzillas is allowed. Here are some shortcuts for often used bugzillas, which should be added bevore the "#" of the bugzilla number:

For other bugzilla numbers, please use the full URL to the coresponding bugzilla. For example:

• http://developer.berlios.de/bugs/?func=detailbug&bug_id=12707&group_id=769

11.2 CVE numbers in changelog

Same as for bugzilla numbers: Add a short description (normally the CVE summary should be enough), the Bugzilla and the CVE number to the changelog entry. Examples:

- Add gdk-pixbuf-226710.patch (#226710, and CVE-2007-0010).
- More XPM fixes: CVE-2005-2975 xpm too many colors DoS (#129642)
- fix ~/.dmrc symlink attack (#180704, CVE-2006-2449)

11.3 Specfile changes

Be as much precise as possible! This is much more important if you remove something from the specfile.

• Removing original source code must be declared in specfile with a comment ("usefull for FreeBSD only" for example) - not necessary to repeat the comment in specfile.
• Extra commands (for example during %install) can be illustrated with a short comment in specfile - this comment should be added to the specfile, too.
• Adding/Removing packages from Requires/Provides must be described in Changelog

11.4 Sourcecode changes

Repeat the most important changes during version upgrade.

• look into the source changelog and pick up the most important changes for the distribution (changes for other operation systems are not important).
• arrange the original changes behind the version update information. Example:

 - Update to 1.3.2:
   + fixes memory leak in import function
   + new API command: unlock_client()
   + the following bugs are closed by this new upstream release:
   ++ ............ [MGN:332]
   ++ .............[MGN:337]
 - split of devel package