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. 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.
  • Possible sources for such newsworthy items are: files called "NEWS" or "ChangeLog" inside the source tree, or the homepage of the project, or a well-known blog of the author that serves as a substitute.
  • If you really cannot find anything in the aforementioned set of places, that is ok. Say so, and carry on. It is not your job to scrape and interpret the Internet for something usable like SCM/git commit logs.

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 [openSUSE:Package_description_guidelines#Summary|summaries], scrap anything related to non-openSUSE platforms.
  • You can use SCM commit messages, if they prove to be useful. If in doubt, don't bother.
  • 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)