openSUSE:Creating a changes file (RPM)

Jump to: navigation, search
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). Small typo fixes are accepted, as is the addition of bug references, and trimming useless trailing whitespace. You may add new components in between older ones. This enables developing a package in more than one branch at a time.

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

Tue Apr 22 20:54:26 UTC 2013 -

- 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

The intent of this changelog is to summarize the most newsworthy items, distilled for an openSUSE user. That means you shouldn't just provide a link to a changelog on the Internet. (Network connections may also be unavailable at the time a user wants to find out about changes.)

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 -

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

- Update to snapshot version
  * Speed of computing primality of a number was improved two-fold
  1. First of all, find out what is new or has changed. Non-exhaustive list of potential sources for newsworthy items:
    1. Files inside the source tree with a name of, or similar to, NEWS, CHANGES, ChangeLog
    2. the homepage of the project
    3. a blog about the software / a blog by the author
    4. an announce post on a mailing list or community site such as
    5. your own experience with the new version.
  2. If you cannot find anything in the aforementioned set of places, that is ok. Say so, and consider it done. (For example, “* No changelog was made available.”) It is not necessary to inspect commit logs or to analyze source code.

Then, assort what you have found with due care:

  1. Don't just copy what you find without reviewing yourself.
  2. 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.
  3. Like with summaries, remove anything about non-openSUSE platforms.
  4. You can use SCM commit messages, if they prove to be useful. If in doubt, don't.
  5. Now, can you, as a package maintainer, make sense of every news item? Does the item mean something to you? If not, then neither does it for the user, and the item in question should be dropped.
  6. If, at this point, there is nothing to report, say so and consider it done. (E.g. “* No user-visible changes” when, for example, upstream only changed the way the software is built.)
  7. Be concise. Pick only the topmost interesting points: If you have over 30 lines of changelog, it is time to stop and refer the user to the other materials (such as upstream-provided news files, web links, …)
  8. Be concise (part 2). Summarize and generalize the points: Don't go too much into specifics of a modification — a suitably interested user can look for implementation details elsewhere.
  9. If there is an 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 it.

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/ 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. For example use bsc#1234 to reference . The full list of issue trackers 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)