openSUSE:Creating a changes file (RPM)
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 an official repository (openSUSE:Factory, Leap, etc.)
- 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 length to 67 characters.
- If creating a list, the first level of indentation must use the dash ('-') as the bullet point symbol, the second level must use the asterisk ('*'). The helper script /usr/lib/build/changelog2spec specifically recognizes this symbols for automatic reindenting. Deeper levels must not be used. Also, yast2-qt will show the log with a proportional rather than monospace font, so potential third levels would display badly.
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. Ideally, it should be more than just a link to a changelog on the Internet (network connectivity is not always a given), but it shall not inundante the user with pages of text. More on that below.
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
- First of all, find out what is new or has changed. Non-exhaustive list of potential sources for newsworthy items:
- Files inside the source tree with a name of, or similar to, NEWS, CHANGES, ChangeLog
- the homepage of the project
- a blog about the software / a blog by the author
- an announce post on a mailing list, community/news sites like freshcode.club or LWN
- your own experience with the new version.
- 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:
- Don't just copy what you find / don't autogenerate, without subsequent review 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.
- 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.
- 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.)
- 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, …)
- 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.
- 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.
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) added foo-1.2.4-buffer-owerflow.patch
- update to Firefox 7 (bnc#720264) [upstream changes here] - 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.
If possible, try to inject in older Factory changelog entries the relevant SLE bugzilla (bsc#) references (when the SLE fix was merged / made obsolete by a version update), CVE references (CVE-...) (they are often fixed by a version update), or SLE Epics task (jsc#SLE-...) (when the feature is about version update / feature update, not for package addition to SLE). Then submit the modified changelog to Factory, it is considered acceptable by review teams.
If it is not possible, you should just use the Factory package as-is without altering changelog, provided that in your SR message (preferably) or as an comment in the submission to SLE:
- 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?).
- For Jira mention in the commit message, make sure you mention the Epic task, not the individual Dev, QA, or Doc issue.
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