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 changes you made. (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.

A .changes file follows these "rules":

  • Use the osc vc command to autocreate a new item with the basic structure and formatting.
  • Add changelog entries in chronological order.
  • List newer changelog entries 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.
  • Limit your maximum line legnth to 67 characters.
  • If you want to create a list, start the list with a dash (-). The second-level bullet point symbol ought to be an asterisk, not a plus sign as is sometimes seen. Third-level or deeper bullet points are not defined. 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.
  • Remenber, yast2-qt will show the log with a proportional font, so do not attempt any indentation beyond the two levels shown here.

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

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. Add the release in the first line after your mail address, for example:

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

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

- Update to snapshot version 1.2.3.456789
  * 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 freshcode.club
    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.

If the latest changelog entry doesn't contain a version, rpmlint shows a no-version-in-last-changelog warning.

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. For example use bsc#1234 to reference https://bugzilla.suse.com/1234 . 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)

Cross Service-Pack merges for SLE

When you are merging cross Service Packs [0] it might not be always possible to cleanly merge Factory changelog i.e. without losing patches added/removed, fixed bugs etc might be getting lost.

In these cases you are allowed to just use the Factory package as-is, provided that in your SR message:

  • You explain which patches get lost and why, is that fixed upstream? Not needed anymore? etc. Patch names are tracked because we do not want to introduce any regressions, you have to explicitly point out the situation with each such patch.
  • You mention the lost bug, jira and once again explicitly state that these are fixed (also tell us how, not needed? Fixed upstream?).

Note that, in no circumstances you are allowed to lose any CVE references, these are very useful for customers.

The main point is **not** that those changes file entries are lost, but the actual fixes get lost. This would mean we introduce regressions into the service pack.

[0] One case is updating Gnome in a new Service Pack in SP2 where SP1 was already diverged from Factory and no longer can be cleanly merged.

Here is a good example, where multiple patches were dropped:

needed due to GNOME 3.34 jsc#SLE-8245

dropped SLE patches:
gtk3-none-pixmap-for-no-background.patch
gtk3-add-gdk_x11_display_get_parent_relative_pattern.patch
gtk3-x11-be-more-careful-about-setting-parent-relati.patch
gtk3-x11-fix-deprecation-macro-use.patch
gtk-use-multiple-font-family-values.patch
gtk3-x11-set-transparent-background.patch