From 2f664f141dafb3def5c4448065fbd9a38157e7aa Mon Sep 17 00:00:00 2001 From: Otto Liljalaakso Date: Apr 02 2023 13:20:52 +0000 Subject: Clarify rules for directory ownership Existing rules for package directory ownership were written in unclear way, leading to wrong interpretation regarding handling of filesystem(-like) package hicolor-icon-theme. The section is rewritten with the following goals: * Start with a clear list that has a separate entry for each case that needs to be considered * Move normative content from examples to main text * Avoid changing the intented interpretation Signed-off-by: Otto Liljalaakso --- diff --git a/guidelines/modules/ROOT/pages/UnownedDirectories.adoc b/guidelines/modules/ROOT/pages/UnownedDirectories.adoc index b322c01..9293b19 100644 --- a/guidelines/modules/ROOT/pages/UnownedDirectories.adoc +++ b/guidelines/modules/ROOT/pages/UnownedDirectories.adoc @@ -4,7 +4,7 @@ The term "unowned directory" (or "orphaned directory") refers to a packaging mis * a package includes files within a directory it creates, but *not* the directory itself * none of the package's dependencies provide the directory either -* the directory belongs to your package and does not belong to any core package or base filesystem package that is considered essential/fundamental to any Fedora System. +* the directory does not belong to the `filesystem` package. == Issues diff --git a/guidelines/modules/ROOT/pages/index.adoc b/guidelines/modules/ROOT/pages/index.adoc index 09f6e51..735f983 100644 --- a/guidelines/modules/ROOT/pages/index.adoc +++ b/guidelines/modules/ROOT/pages/index.adoc @@ -2513,24 +2513,32 @@ For more details, please refer to xref:LicensingGuidelines.adoc#subpackage-licensing[Subpackage Licensing]. Directory ownership is a little more complex than file ownership. -Packages must own all directories they put files in, except for: +Every directory where a package installs files MUST be owned in one of the following ways: -* any directories owned by the `+filesystem+`, `+man+`, -or other explicitly created `+-filesystem+` packages -* any directories owned by other packages -in your package's natural dependency chain +* the package owns the directory directly by listing it in `+%files+` +* another package in its direct or transitive dependencies owns the directory +* the `+filesystem+` package owns the directory -In this context, a package's "natural dependency chain" is defined -as the set of packages necessary for that package to function normally. -To be specific, you do not need to require a package for the sole fact -that it happens to own a directory that your package places files in. -If your package already requires that package for other reasons, -then your package should not also own that directory. +A package MAY own a directory that is also owned by another package. +In that case, ownership and permissions on the directory MUST match in all packages that own it. +This situation commonly occurs if package A places files in a directory used by package B +in order to enhance or add functionality to package B, +but package B is not needed for A to function correctly. -In all cases we are guarding against unowned directories -being present on a system. -Please see xref:UnownedDirectories.adoc[Packaging:UnownedDirectories] -for the details. +A package MAY Require another package for the sole purpose of ensuring directory ownership. +Usually in this case, the Required package contains only a directory structure and possibly some metadata. +Examples of such _filesystem packages_ are `+hicolor-icon-theme+` and `+mozilla-filesystem+`. +If a directory is owned by a filesystem package, +other packages SHOULD Require the filesystem package instead of directly owning the directory. + +When determining whether to create a filesystem package, +packagers should consider the number of affected directories and packages, +and use their own best judgement to determine if a filesystem package is necessary or not. + +See xref:UnownedDirectories.adoc[Packaging:UnownedDirectories] +for the rationale behind requiring every directory to be owned by some package. + +=== Examples IMPORTANT: When co-owning directories, you *must* ensure that the ownership and permissions @@ -2539,7 +2547,7 @@ 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 +==== The directory is wholly contained in your package, or involves core functionality of your package An example: @@ -2550,7 +2558,7 @@ gnucash places many files under the /usr/share/gnucash directory Solution: the `+gnucash+` package should own the `+/usr/share/gnucash+` directory -=== The directory is also owned by a package implementing required functionality of your package +==== The directory is also owned by a package implementing required functionality of your package An example: @@ -2563,7 +2571,7 @@ gdm depends on pam to function normally, and would Require: pam (either implicit Solution: the `+pam+` package should own the `+/etc/pam.d+` directory, and `+gdm+` should `+Require:+` the `+pam+` package. -=== The directory is owned by a package which is not required for your package to function +==== The directory is owned by a package which is not required for your package to function Some packages create and own directories with the intention of permitting other packages to store appropriate files, @@ -2584,26 +2592,31 @@ Solution: the `+evolution+` package should own the There is no need to add an explicit Requires on gtk-doc solely for the directory ownership. -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 +==== The directory is owned by a filesystem package + +An example: + +.... +hicolor-icon-theme owns the /usr/share/icons/hicolor/scalable/apps directory +dosbox-x puts a file into /usr/share/icons/hicolor/scalable/apps +dosbox-x does not need hicolor-icon-theme in order to function properly +hicolor-icon-theme is a filesystem package +.... + +Solution: `+dosbox-x+` should Require `+hicolor-icon-theme+`. + +==== The directory is owned by `+filesystem+` + +An example: + +.... +filesystem own the /usr/share/man/man1 directory +vim-common puts a file into /usr/share/man/man1 +.... + +Solution: Ownership of directories included in `+filesystem+` is always ensured. + +==== 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: