From 3513a8292bd45c0121350310f59b4c8684403d17 Mon Sep 17 00:00:00 2001 From: Igor Gnatenko Date: Sep 24 2018 13:20:33 +0000 Subject: index: add missing notes Signed-off-by: Igor Gnatenko --- diff --git a/guidelines/modules/ROOT/pages/index.adoc b/guidelines/modules/ROOT/pages/index.adoc index 9c097b8..134bd3f 100644 --- a/guidelines/modules/ROOT/pages/index.adoc +++ b/guidelines/modules/ROOT/pages/index.adoc @@ -744,6 +744,9 @@ readelf -d /usr/bin/myapp | grep RPATH 0x0000000f (RPATH) Library rpath: [/usr/lib/myapp] .... +TIP: *Non-Internal Libraries*: When programs outside of the package are supposed to link against the library, it is better to use the <> or simply move the libraries into `+%{_libdir}+` instead. That way the dynamic linker can find the libraries without having to link all the programs with an rpath. + +[#alternatives-to-rpath] === Alternatives to Rpath Often, rpath is used because a binary is looking for libraries in a non-standard location (standard locations are /lib, /usr/lib, /lib64, /usr/lib64). If you are storing a library in a non-standard location (e.g. /usr/lib/foo/), you should include a custom config file in /etc/ld.so.conf.d/. For example, if I was putting 32 bit libraries of libfoo in /usr/lib/foo, I would want to make a file called "foo32.conf" in /etc/ld.so.conf.d/, which contained the following: @@ -1174,6 +1177,8 @@ In this context, a package's "natural dependency chain" is defined as the set of In all cases we are guarding against unowned directories being present on a system. Please see xref:UnownedDirectories.adoc[Packaging:UnownedDirectories] for the details. +IMPORTANT: When co-owning directories, you *must* ensure that the ownership and permissions on the directory match in all packages that own it. + Here are examples that describe how to handle most cases of directory ownership. === The directory is wholly contained in your package, or involves core functionality of your package @@ -1215,6 +1220,8 @@ Solution: the `+evolution+` package should own the `+/usr/share/gtk-doc+` direct Sometimes, it may be preferable for such directories to be owned by an "artificial filesystem" package, such as `+mozilla-filesystem+`. These packages are designed to be explicitly required when other packages store files in their directories, thus, in such situations, these packages should explicitly Require the artificial filesystem package and not multiply own those directories. Packagers should consider the number of affected directories and packages when determining whether to create artificial filesystem packages, and use their own best judgement to determine if this is necessary or not. +TIP: *Rule of Thumb*: When determining whether this exception applies, packagers and reviewers should ask this question: Do the files in this common directory enhance or add functionality to another package, where that other package is not necessary to be present for the primary functionality of this package? + === The package you depend on to provide a directory may choose to own a different directory in a later version and your package will run unmodified with that later version An example involving Perl modules: @@ -1411,6 +1418,8 @@ There are specific guidelines for handling tmpfiles.d configurations and directo == Renaming/Replacing Existing Packages +NOTE: FESCo has a https://fedoraproject.org/wiki/Package_Renaming_Process#Re-review_required[package renaming policy] that should be followed when renaming an existing package. + In the event that it becomes necessary to rename or replace an existing package, the new package should make the change transparent to end users to the extent applicable. If a package is being renamed without any functional changes, or is a compatible enough replacement to an existing package (where "enough" means that it includes only changes of magnitude that are commonly found in version upgrade changes), provide clean upgrade paths and compatibility with: @@ -1424,6 +1433,8 @@ $provEVR refers to an (Epoch-)Version-Release tuple the original unchanged packa If a package supersedes/replaces an existing package without being a sufficiently compatible replacement as defined above, use only the `+Obsoletes:+` line from the above example. +CAUTION: *Take `+%{?dist}+` into account*: When deciding what $obsEVR should be, remember that it needs to be higher than the previous `Release:` with `+%{?dist}+` expanded. Example: if the package previously had `+Release: 4%{?dist}+` the release in $obsEVR should be at least 5. + If retired packages need to be removed from end user machines because they cause dependency issues which interfere with upgrades or are otherwise harmful, a packager MAY request that `+Obsoletes:+` be added to `+fedora-obsolete-packages+`. Simply file a bugzilla ticket https://bugzilla.redhat.com/enter_bug.cgi?product=Fedora&version=rawhide&component=fedora-obsolete-packages[here]. Please include information on which packages need to be obsoleted, the exact versions which need to be obsoleted, and the reasons why they cannot be allowed to remain installed. If the obsoleted package had an Epoch set, it must be preserved in both the `+Provides:+` and `+Obsoletes:+`. For example, assume foo being renamed to bar, bar is compatible with foo, and the last foo package release being foo-1.0-3%\{?dist} with Epoch: 2. The following should be added to bar (and similarly for all subpackages as applicable):