[Guidelines Change] Conflicts

[Tom "spot" Callaway]

A new document was added to the Packaging/ hierarchy: Conflicts.
This document is also linked from the Packaging/Guidelines.

For convenience, the contents of the current Packaging/Conflicts policy
is presented below:

================

Conflicts
Whenever possible, Fedora packages should avoid conflicting with each
other. Unfortunately, this is not always possible. 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: 

# If the unrar utility is present, super-unpacker can open rar files. However, it only works with unrar >= 2.0. Unrar is not required for this app to function.
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. 

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. 

Conflicting Files
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
      * Put the library in a subdirectory of /usr/lib or /lib and
        include a ld.so.conf file in /etc/ld.so.conf.d/. 

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 "alternatives" to let the end user to select which
        generic name is the default. Note that this is usually not the
        case. 

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.

~spot