Packaging:Conflicts

This is an old copy of a packaging guideline, preserved here in the wiki while we complete the transition to the Fedora documentation system. The current version is located at https://docs.fedoraproject.org/en-US/packaging-guidelines/Conflicts/. Please update your bookmarks.

Conflicts Guidelines

Author: Tom 'spot' Callaway
Revision: 0.07
Initial Draft: Tuesday Dec 5, 2006
Last Revised: Wednesday Oct 31, 2012

Conflicts

Users should always be able to install the latest packages from Fedora's repos regardless of what other Fedora packages are installed. Therefore, whenever possible, the latest Fedora packages of a release should avoid conflicting with each other. Conflicts result in a transaction set where the user has to decipher the error message and make some sort of decision. The transaction set doesn't provide information to the user about why two packages conflict to help them make an informed decision.

As Fedora packagers, we try to make it so that any subset of latest Fedora's packages will install and run. Unfortunately, this is not always possible but we can usually make it so that conflicting packages can be installed and the user can decide which package to enable afterwards. In the few remaining cases, we have to use Conflicts: tags. These guidelines illustrate how conflicts should be handled in Fedora, specifically concerning when and when not to use the Conflicts: field.

Acceptable Uses of Conflicts:

As a general rule, Fedora packages must NOT contain any usage of the Conflicts: field. This field is commonly misused, when a Requires: would usually be more appropriate. It confuses depsolvers and end-users for no good reason. However, there are some cases in which using the Conflicts: field is appropriate and acceptable.

Implicit Conflicts

Keep in mind that implicit conflicts are NEVER acceptable. If your package conflicts with another package, then you must either resolve the conflict, or mark it with Conflicts:.

Optional Functionality

Some software can utilize other optional software applications if present, but do not require them to be installed. If they are not installed, the software will still function properly. However, if those other "optional applications" are too old, then the software won't work. This is an acceptable use of the Conflicts: field. The packager must document the reason in a comment above the Conflicts: field:

Example:

Conflicts: unrar < 2.0

If the software links to the libraries of another package, it must use Requires: instead of Conflicts: to mark that dependency. Also, if the software does not function properly without another package being installed, it must use Requires: instead of Conflicts:.

The packager should ask:

If the package (at the correct version) in Conflicts: is not present, will my package be functional?

If the answer is yes, then it is probably a valid use of Conflicts:. If the answer is no, then it is almost certainly a better case for Requires:.

For example, if foo-game needs libbar to run, but will not work with libbar that is older than 1.2.3:

WRONG: Conflicts: libbar < 1.2.3
RIGHT: Requires: libbar >= 1.2.3

Packagers should keep usage of Conflicts: to a bare minimum. Only upgrading from two previous release of Fedora is supported, so Conflicts against older packages than that, while technically correct, are unnecessary, and should not be included.

Splitting Packages

If contents from one package are split into a separate package the new package usually contains files that also appear in the original package which might lead to a implicit conflict between the files in the new package and the original package. Where the new package depends on the original package, this can be resolved with a versioned Requires:

# In the new package's spec file:
Requires: original-package > EVR_BEFORE_SPLIT

If the new package should be installable independently of whether the original package is installed, a versioned conflict is allowed:

# In the new package's spec file:
Conflicts: original-package <= EVR_BEFORE_SPLIT

In both of these cases, the new version of the original package should be updated to not contain the conflicting files and to depend on the new package (at least in all stable Fedora releases). This allows to install the latest releases of both packages without any problem. The Conflicts are only there to resolve the case where the new package is installed and the older version of the original package was already installed.

Compat Package Conflicts

It is acceptable to use Conflicts: in some cases involving compat packages. These are the cases where it is not feasible to patch applications to look in alternate locations for the -compat files, so the foo-devel and foo-compat-devel packages need to Conflict:. Whenever possible, this should be avoided.

Incompatible Binary Files with Conflicting Naming (and stubborn upstreams)

In the specific case where multiple software components generate identically named (but incompatible) binaries, Fedora Packagers should make every effort to convince the upstreams to rename the binaries to resolve the conflict (see: Packaging:Conflicts#Binary_Name_Conflicts). However, if neither upstream is willing to rename the binaries to resolve the conflict, AND the binaries are not viable candidates for alternatives or environment modules (incompatible runtimes), as long as there are no clear cases for both packages to be installed simultaneously, explicit Conflicts are permitted at the packager's discretion. Both packages must carry Conflicts in this case.

Be aware, adding explicit Conflicts means that if any other packages depend on your package, you may be creating a chain-of-conflicts that could cause user pain. Please consider this as a last resort.

Common Conflicting Files Cases and Solutions

There are many types of files which can conflict between multiple packages. Fedora strongly discourages using Conflicts: to resolve these cases. Here are some suggestions which can be used to resolve these conflicts (note that not all file conflict cases are listed, nor are all possible solutions):

Man Page Name Conflicts

• Rename the man pages to slightly alter the suffix of the man page (e.g man1/check.1.gz and man1/check.1foo.gz)
• Rename the man pages to include a prefix of the providing package (e.g. foo-check.1.gz and bar-check.1.gz)

Library Name Conflicts

If the library is 100% ABI-compatible, you can use Environment Modules to let the user switch between them. If the library is not 100% ABI-compatible get one of the upstreams to rename. See Approaching Upstream for ideas on persuasion. If neither upstream will budge open a ticket for FPC to evaluate what sort of hoops both packages would need to implement to not conflict at runtime.

Header Name Conflicts

• Put the headers in a subdirectory of /usr/include.

Binary Name Conflicts

• Convince upstream to rename the binaries to something less generic (or just less conflicting).
• In the case where the conflicting binaries provide the same functionality, you can then rename the binaries with a prefix, and use Packaging:Alternatives to let the system administrator select which generic name is the default. Note that this is usually not the case.
• In cases where the binaries provide similar functionality Packaging:EnvironmentModules may be an option. This is more flexible than alternatives and is for things that each individual on a system may want to choose between rather than a system administrator.

Approaching Upstream

When renaming or putting files into subdirectories, it is a good idea to try to get upstream to rename their conflicting files (for instance if they both had commands named %{_bindir}/trash). Doing some research about which has been around longer may be useful in this case but may or may not be persuasive to upstream.

If neither upstream renames, we would then approach other distributions (distributions-list[at]freedesktop.org is a good place to discuss this) about renaming that can be done in all distros. That helps end users going from one distro to another to have consistency. Length of time that the projects have been around, how popular each is, and numerous other factors may play a role in this decision. Once a decision is made, we would rename the Fedora packages to match.

Potential Conflicting Files

We don't just try to avoid conflicts with existing packages within Fedora but also potential conflicts. This is because the first package to enter Fedora is not always the one that should take on the name. There are several scenarios in which this could come into play:

1. There is a conflicting package that is not in Fedora yet (found by doing a web search, for instance)
2. There is no conflict yet but the filename is likely to be used by another project (something like /usr/bin/parser)

In the first case, where a conflicting package is known to exist but is not yet in Fedora, we should go through the process of determining which package has a more valid claim to the name and rename the files in the package we're including if it doesn't have the more valid claim. If you think your situation is unique, please send email to fedora-devel-list[at]redhat.com to make your case.

In the second case, where there is no known package to conflict with at this time, it is up to the packager to make a decision. Note that it is encouraged that you at least speak to upstream about the potential for conflicts. However, we can hope that any later projects that attempt to use that name can be persuaded to rename based on this project being around longer.

Standard Commands

Common names are allowed for standard commands since those will be the only commands to implement them. Standard commands include things provided for in published and widely implemented standards like POSIX and de facto standards such as a program that has traditionally been shipped with a certain filename as part of a large number of Unix variants. If in doubt, send a message to fedora-devel-list[at]redhat.com with details of what standards the command appears in, how long it's been available on what Unix systems, and whether you've found any conflicting programs that implement a substantially different command with the same filename.

Conflicting Package Names

Just as files can conflict, package names can as well. Conflicting package names MUST be resolved. Package names which differ only in case are still considered to be conflicting. You should follow the same basic steps outlined in #Approaching_Upstream

Renaming packages and replacing them with others can be difficult if it has to occur at a later time (for instance, upgrade paths can become complex in these situations) so it is even more important to be aware of potential conflicts here than it is with filenames.

Other Uses of Conflicts:

If you find yourself in a situation where you feel that your package has to conflict with another package (either explicitly or implicitly), but does not fit the documented accepted cases above, then you need to make your case to the Fedora Packaging Committee. If they agree, then, and only then can you use Conflicts: in a Fedora package. Remember, whenever you use Conflicts:, you are also required to include the reasoning in a comment next to the Conflicts: entry, so that it will be abundantly clear why it needed to exist.