Home Wiki > openSUSE:Creating a changes file (RPM)
Sign up | Login

openSUSE:Creating a changes file (RPM)

tagline: From openSUSE

This article will give you a hints from the openSUSE review team how to write a good and useful changes entry.

Changelog section (%changelog)

Every time you make changes to the package, you must add a changelog entry. This is important not only to have an idea about the history of a package, but also to enable users, fellow packagers, and QA people to easily spot the changes that you make. (The osc log is underused, as it does not support linking history à la git merge when an SR is accepted.)

The Open Build Service uses a separate file for package changes. This file is called like the specfile, but has .changes at the end instead of .spec. The `osc vc` command can be used to autocreate a new item with the basic structure and formatting. Changelog entries have to be in chronological order. Newer changelog entries are listed in the file above older entries, thus the first entry is the most recent one. You shall not modify any existing component (where component is a text enclosed between ----------) if a package is checked in to the official repository (openSUSE:Factory). Exception: small typo fixes are accepted. As well as you might add new components in between older ones. This enables you to develop package in more than one branch at the time.

Entries in this changes file shall have the following structure/formatting styles:

Tue Apr 22 20:54:26 UTC 2013 - your@email.com

- level 1 bullet point; long descriptions
  should wrap
  * level 2 bullet point; long descriptions
    should wrap
  * another l2 bullet point
- another l1 bullet point

Note: The recommended maximal length per line is 67 chars (equal to the dashed line/separator). Third-level or deeper bullet points are not defined. yast2-qt will show the log with a proportional font, so do not attempt any indentation beyond the two levels shown here.

The second-level bullet point symbol ought to be an asterisk, not a plus sign as is sometimes seen. The helper script /usr/lib/build/changelog2spec specifically recognizes the asterisk and will reflow such bullet points for the RPM changelog (inspectable `rpm -q --changelog`) should they not already be at the second indentation level.

What goes into the changelog

Version updates

If a version update was done, that should definitely be in the .changes file, for example like so:

Tue Apr 22 20:54:26 UTC 2013 - your@email.com

- Update to new upstream release x.y.z:
  * bling and changes from upstream for that version
  * just the relevant parts, no info about other OS
  * and keep it as short as possible
Tue Apr 22 20:54:26 UTC 2013 - your@email.com

- Update to snapshot version
  * Speed of computing primality of a number was improved two-fold
  • Don't just provide a link to a changelog on the Internet. (Network connections may be out at the time a user wants to find about changes.)
  • Provide a general overview of the new features and behavioral changes. Don't go too much into specifics of a modification — a suitably interested user can look for implementation details elsewhere. But provide at least a good overview so people know why something has changed (because that's normally why there is a new release, right?) or that a bug has been fixed that might have affected some users.
  • Whenever there is an "API incompatible change", that requires the user to adapt their configuration and/or setup, this should be mentioned in the changelog of the package, too, to make the users aware of those incompatible changes.
  • Possible sources for newsworthy items are: Files inside the source tree with a name of, or similar to, NEWS, CHANGES, ChangeLog; or the homepage of the project, or a blog about the author/software, or your own experience with the new version.
  • Try to provide something around one or two lines per bug reference or version number that helps people to get the idea.
  • If you really cannot find anything in the aforementioned set of places, that is ok. Say so, and carry on. (For example, “* No changelog was made available.”) It is not required to inspect commit logs or to analyze source code diffs to the previously shipped version.
  • If there in fact is nothing to report, express this too. (E.g. “* No user-visible changes” when upstream only changed the way to build the package.)

Once you have something like a list of presentable items, it is time to assort them with due care:

  • Don't just copy what you find without reviewing yourself.
  • Avoid and trim anything related to the build procedure of the package if it has no visible effect on the user. The software is already built by the time it reaches the user.
  • Like with summaries, remove anything about non-openSUSE platforms.
  • You can use SCM commit messages, if they prove to be useful. If in doubt, don't.
  • For each bullet point that you pick up: Can you, as a package maintainer, make sense of it? If not, then the user probably cannot either, and the line in question should be removed.
  • Be concise. If you have over 30 bullet points for a version update, trim some of the less-interesting parts, and refer the user to an extended changelog elsewhere.

You can, optionally, add the original upstream change documents to the package as a file as a reference. This however is only in addition to something in .changes.

Distro-related changes

Besides version updates, there may be changes related to the openSUSE packaging itself. Noteworthy items about that would simply be appended.

- update to new upstream release 2.0 (if not, omit)
  * this and that as per above
- Added new BuildRequires glibc-devel: new dependency
- Do magic trick in install section to overcome installation failure
- add foobar-fix-ham.patch: <give a reason>
- add foobar-remove-spam.patch: <give a reason>
- modify foobar-autotools.patch: <give a reason>
- remove foobar-libpng15-compat.patch: <give a reason>  
- ... (other changes done to the package)
  • Document the changes for future package changes. It can help in identifying if some hack is still needed (the hack in the .spec should have a comment anyway) and when it was added.
  • Make the life for any reviewer easier: a short explanation why something is the way it is helps with annoying declines due to misunderstandings. (This sometimes should go into .spec, whereever appropriate.)

Referring to upstream ChangeLog

While it might sound like a good idea in the first run, a simple reference to the place of the upstream Changelog (especially if it is tracked on GitHub or other popular collaboration plattforms) is NOT such a good idea.

  • if you reference the Changelog in the "master" branch in your changes file, this file might have changed already. Making it really hard to identify which version your changes file entry belongs to
  • People with limited internet access (yes: such people still exist) need not only to download the package but also need to open the link (...and we are not starting the discussion on how to extract it from your changes file here) to really see what happened

So - whenever possible - please try to follow the two simple suggestions:

  • put the most important upstream changes in your changes file, so your package users can get an idea about important changes. 10-15 lines should be enough for this.
  • refer to a Changelog file which is installed together with your package (normally under /usr/share/doc/packages/$name/Changelog.md or similar), so people can read the full details without the need to open an internet connection.

Bug fix, feature implementation

Anytime you have fixed a bug (or implemented the feature), you have to mention the number of bug in changes. As fix should be reported in upstream bugzilla, it is better to add a prefix before the number, so people will know where to find an information.

Prefix Bug tracker
bsc# bugzilla.suse.com
bnc# bugzilla.novell.com
fate# fate.suse.com
bko# bugzilla.kernel.org
kde# bugs.kde.org
bgo# bugzilla.gnome.org
bmo# bugzilla.mozilla.org

The full list is available on Current set of abbreviations.

In case the issue has some external identifier, like CVE number, it should be added as well. There are more common ways how to format the message

   - update to Firefox 13.0 (bnc#765204)
     * MFSA 2012-34/CVE-2012-1938/CVE-2012-1937/CVE-2011-3101
       Miscellaneous memory safety hazards
  - Fix string quoting.  [bnc#666416]
  - Add xz BuildRequires because we can't build a package for a
    xz-compressed tarball without explicitly specifying that... See
    bnc#697467 for more details.
  - fix bnc#595144 - Compiled binary in ant

Package updates

In case of package update, the new version have to be mentioned in changes. It is often useful to provide some basic changes from upstream changelog. In case upstream does not provide it, you have to still provide that information in the .changes file, such as

 - update to foo 1.2.3: no changelog available
 - update to Firefox 13.0.1
   * bugfix release

Patches changes

All changes in patches must follow the Patches guidelines. It is always a good idea to put the patch name behind the line describing the fix

 - fix segfault on load incorrect document (bnc#123456)
   * foo-1.2.4-buffer-owerflow.patch
 - update to Firefox 7 (bnc#720264)
   * removed obsolete mozilla-cairo-lcd.patch (upstream)