From c95aefe86ce1b73be36767ebfe96f56f9c32b0d7 Mon Sep 17 00:00:00 2001 From: Didik Supriadi Date: Jul 25 2021 23:29:50 +0000 Subject: Fix broken links and formatting in Conflicts.adoc --- diff --git a/guidelines/modules/ROOT/pages/Conflicts.adoc b/guidelines/modules/ROOT/pages/Conflicts.adoc index de61b05..a905d3b 100644 --- a/guidelines/modules/ROOT/pages/Conflicts.adoc +++ b/guidelines/modules/ROOT/pages/Conflicts.adoc @@ -17,7 +17,7 @@ As a general rule, Fedora packages must NOT contain any usage of the `+Conflicts === 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 @@ -41,7 +41,7 @@ For example, if foo-game needs libbar to run, but will not work with libbar that *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 @@ -67,7 +67,7 @@ It is acceptable to use `+Conflicts:+` in some cases involving compat packages. === 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. +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. @@ -82,7 +82,7 @@ There are many types of files which can conflict between multiple packages. Fedo === Library Name Conflicts -If the library is 100% ABI-compatible, you can use Packaging:EnvironmentModules[ 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 Packaging:Conflicts#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 @@ -91,8 +91,8 @@ If the library is 100% ABI-compatible, you can use Packaging:EnvironmentModules[ === 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. +* 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 @@ -130,7 +130,7 @@ 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 +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.