| |
@@ -7,21 +7,53 @@
|
| |
|
| |
== 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.
|
| |
+ 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.
|
| |
+ 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:+`.
|
| |
+ 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:
|
| |
+ 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:*
|
| |
|
| |
@@ -29,60 +61,120 @@
|
| |
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:+`.
|
| |
+ 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 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:+`.
|
| |
+ 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:
|
| |
+ 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.
|
| |
+ 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:
|
| |
+ 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:
|
| |
+ 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.
|
| |
+ 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.
|
| |
+ 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: xref:#_binary_name_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.
|
| |
+ 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: xref:#_binary_name_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):
|
| |
+ 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)
|
| |
+ * 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 xref:EnvironmentModules.adoc[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 xref:#_approaching_upstream[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.
|
| |
+ If the library is 100% ABI-compatible, you can use
|
| |
+ xref:EnvironmentModules.adoc[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 xref:#_approaching_upstream[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
|
| |
|
| |
@@ -90,50 +182,111 @@
|
| |
|
| |
=== 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 xref:Alternatives.adoc[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 xref:EnvironmentModules.adoc[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
|
| |
+ * 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 xref:Alternatives.adoc[Alternatives]
|
| |
+ to let the system administrator select which generic name is the default.
|
| |
+ Note that this is usually not the case.
|
| |
|
| |
- 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.
|
| |
+ * In cases where the binaries provide similar functionality
|
| |
+ xref:EnvironmentModules.adoc[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.
|
| |
|
| |
- 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:
|
| |
+ === Approaching Upstream
|
| |
|
| |
- 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+`)
|
| |
+ 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.
|
| |
|
| |
- 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.
|
| |
+ == Potential Conflicting Files
|
| |
|
| |
- 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.
|
| |
+ 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.
|
| |
+ 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 xref:#_approaching_upstream[Approaching Upstream].
|
| |
+ 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
|
| |
+ xref:#_approaching_upstream[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.
|
| |
+ 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 https://pagure.io/packaging-committee[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.
|
| |
+ 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
|
| |
+ https://pagure.io/packaging-committee[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.
|
| |
tibbs
commented 2 years ago
This converts a few more of the guidelines pages to use semantic breaks.
I'm starting to run out of steam for doing these so I will probably take a break.
I've accumulated a big list of minor fixes in the pages I've converted so I'll be working on those next.