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

Cancel

Navigation

Help

Toolbox

Sponsors

openSUSE:Creating a changes file (RPM)

tagline: From openSUSE

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

Contents

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 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, and will be handled verbatim.

A common update to version x.y.z would look similar to: 

-------------------------------------------------------------------
Tue Apr 22 20:54:26 UTC 2013 - your@email.com
- Update to version 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
- 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)

General format:

  • Start with version updates, incl. buzz about the update
  • mention general changes in the .spec file; two reasons for this:
    • 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.

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
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)
Retrieved from "http://en.opensuse.org/openSUSE:Creating_a_changes_file_(RPM)"