Packaging/Patches

From openSUSE

We deal with lots of packages, and lots of patches inside those packages, so this page serves as a way to better organize the patches and the way we deal with them.

Patch Standards

Patches need to be marked in the .spec files with a well-known format to be able to run automatic tools on them, in order to generate reports, patch counts and other interesting information. They also need to be named consistently.

Patch Markup (also called "Tagging Patches")

To facilitate the use of automatic tools -- and to help future packagers -- we have agreed on using the following categories for our patches:

• Fixes: these are normal fixes and are divided into two categories:
  • Fixes for openSUSE-specific things, that upstream maintainers won't be interested in.
  • Fixes for SLE-specific things, that upstream maintainers won't be interested in and that are not needed in openSUSE.
  • Fixes for the upstream sources that should be upstreamed.
• Features: new features added to the packages, also divided into two categories:
  • Features for openSUSE-specific things (AppArmor integration, for instance) with no interest for upstream maintainers.
  • Features for SLE-specific things with no interest for upstream maintainers or openSUSE.
  • Features that should be upstreamed. Whenever we write this kind of new feature, it is important to coordinate with upstream maintainers. That way, we can develop something that will be accepted upstream without changes. Once a feature is finished, it is a lot of work to rework it to be acceptable to upstream maintainers. As such, it's better to know from the beginning exactly what upstream maintainers would expect.

To mark our patches to follow this convention, we have came up with a standard to mark them in the .spec file, following the format below:

# PATCH-FIX-OPENSUSE fix-for-opensuse-specific-things.patch bnc#123456
Patch1: fix-for-opensuse-specific-things.patch
# PATCH-FIX-SLE fix-for-sle-specific-things.patch bnc#123456
Patch2: fix-for-sle-specific-things.patch
# PATCH-FIX-UPSTREAM fix-for-upstream-sources.patch bnc#123456
Patch3: fix-for-upstream-sources.patch
# PATCH-FEATURE-OPENSUSE feature-for-opensuse-specific-things.patch bnc#123456
Patch4: feature-for-opensuse-specific-things.patch
# PATCH-FEATURE-SLE feature-for-sle-specific-things.patch bnc#123456
Patch5: feature-for-sle-specific-things.patch
# PATCH-FEATURE-UPSTREAM feature-for-upstream.patch bnc#123456
Patch6: feature-for-upstream.patch

Special case: we often have patches that get commented out temporarily because they failed to apply to the latest sources, and the patches need to be rebased. Don't comment out the patch's declaration, but do comment out its application. When marking a patch as needing a rebase, it's a good idea to preserve its old tag.

# PATCH-NEEDS-REBASE old-patch.patch bnc#123456 -- Does something old.  Was: PATCH-FEATURE-OPENSUSE
Patch7: old-patch.patch
[...]
# %patch7

Finally, we include email addresses, so it'll be easier to figure out who wrote a patch if we have questions later, and free-form comments after " -- ".

That is:

# PATCH-{FIX|FEATURE}-{OPENSUSE|SLE|UPSTREAM} name-of-file.patch bnc#[0-9]* you@example.com -- this patch makes things totally awesome

If there are related bugs in Novell or other bugzillas, please add them, it will help us to get more accurate information. If there are two or more available then it's preferable to list both (or more).

You can find the current set of abbreviations at the end of this document. We can also define more abbreviations later if and when they prove necessary.

Some patches fix bugs that aren't explicitly recorded anywhere. The right thing to do in this case requires some judgment on the part of the packager, but here are some ideas:

• If a release is imminent, create a bug for it. This is usually a requirement, and even if it weren't, it's still the right thing to do.
• If a release is a long way off and the bug has already been fixed upstream, note in the comment that it's already fixed in svn (or wherever) and the patch will go away when we next upgrade.

Patch Naming

All new patches should end with the extension '.patch'.

Whether a patch's name should start with the name of the package it applies to is a matter of debate or style. When in doubt, follow the convention used in the package you're hacking on.

Do NOT use %{version} macro in Patch: line, specify the version by hand. Using the macro:

• causes lots of renames on version update
• makes it easy to overlook patches that are no longer needed
• makes it hard to determine when the patch was touch for the last time
• makes it easy to find out when the patch broke (package archaelogy)

An exception to this exists: patches that fix warnings that the compiler emits due to bogus code are frequently named 'abuild.patch'.

The patchlevel -- that is, will a patch be applied with -p0 or -p1? -- isn't important. Create patches however they're comfortable for you.

Current set of abbreviations

To avoid confusion and double burden, referencing to other bugzillas is allowed. Here are some shortcuts for often used bugzillas, which should be added before the "#" of the bugzilla number. Note there is no whitespace between the shortcut and the bugzilla number.

For other bugzilla numbers, please use the full URL to the coresponding bugzilla at the beginning of the patch file. For example:

• http://developer.berlios.de/bugs/?func=detailbug&bug_id=12707&group_id=769

Abbreviation Bookmarklet

A bookmarklet for searching bugzilla.novell.com with bnc# prefixes can be found here