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 General information

• openSUSE uses a separate file for package changes. This file is called like the specfile, but has *.changes instead of *.spec as ending.
• entries in this changes file have the following structure:

-------------------------------------------------------------------
Tue Apr 22 20:54:26 CEST 2008 - your@email.com

-

A new entry starts with 67 '-' delimiters below is the current date in posix format, a delimter separated by whitespace, and the email address of the responsible packager third line is an empty line each change is listed with a starting '-' - you can use other delimiters for grouping changes last line is again empty

The package 'osc' comes with a tool named buildvc which can be used to create a valid changes entry.

11.2 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).

Current set of abbreviations

11.3 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.4 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 ("useful 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.5 Sourcecode changes

Repeat the most important changes - but not too much.

• look into the source changelog and pick up the most important changes for the distribution (changes for other operation systems are not important). What has changed in the new version, usually in the level of detail of a NEWS file, the changelog files are usually too long. More than 10-15 lines shouldn't be necessary to describe the most important changes.
• 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

• If upstream does not provide a meaningful changelog, then only do best effort. Don't waste too much time over it. See [[1]] for a discussion on best practises.
• If the upstream tarball really has not changed except for the version number, just the version number in the changelog would be fine. Same goes for packages just containing some graphics or theming (unless upstream already provides something that fits). If the upstream changes just consist of "updated translation" or "several bugfixes" even that can be sufficient for a changelog entry (unless these bugfixes contain something you find worth mentioning).