packaging-committee

Clone
Source Code
GIT

#1061 Clarify rules for directory ownership
Opened 3 years ago by oturpe. Modified a year ago
oturpe/packaging-committee hicolor-filesystem  into  master

Merge
file modified
+1 -1 
@@ -4,7 +4,7 @@ 
 

  

  * 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

file modified
+51 -38 
@@ -2513,24 +2513,32 @@ 
 

  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 @@ 
 

  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 @@ 
 

  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 @@ 
 

  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 @@ 
 

  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:

EDIT: Completely rewritten based on discussion in the Packaging mailing list

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 have a separate entry for each case that needs to be considered
  • Move normative content from examples to main text
  • Avoid changing the indented interpretation

2 new commits added

  • List hicolor-icon-theme explicitly as filesystem package
  • Minor typo and formatting fixes
3 years ago

2 new commits added

  • Clarify rules for directory ownership
  • Minor typo and formatting fixes
3 years ago

This would seem to be a different change.

This also seems a change unrelated to directory ownership.

Yes, those two are the "Also, minor typo and formatting fixes." part, a separate commit. They can be dropped if combining that kind of changes with the real content is not desired.

The list and this paragraph are a bit confusing, I think because the "a required package owns the directory" case is split into two.

Let me try to simplify this, maybe to something like:

  • the package itself owns the directory
    by listing it in +%files+ with a %dir directive
  • another package in its direct or transitive dependencies
    owns the directory
  • the filesystem package owns the directory

This also allows you to simplify the following paragraphs.

3 new commits added

  • Simplify wording for directory ownership
  • Clarify rules for directory ownership
  • Minor typo and formatting fixes
3 years ago

rebased onto becb6ddbc46de437d20bfd5d28fbadbd759f69b0
3 years ago

The list and this paragraph are a bit confusing, I think because the "a required package owns the directory" case is split into two.

Let me try to simplify this, maybe to something like:

  • the package itself owns the directory
    by listing it in +%files+ with a %dir directive
  • another package in its direct or transitive dependencies
    owns the directory
  • the filesystem package owns the directory

This also allows you to simplify the following paragraphs.

Yes, that is true, there is no real need to separate between "natural dependencies" and "filesystem package dependencies" in this list. I was mainly concerned with getting the special filesystem package on its own row and more or less kept the rest as they were initially.

I added another commit than changes the list to your suggestion and attempts to simplify the following prose as much as possible while still discussing the difference between shared ownership and filesystem packages.

rebased onto 67722c05eaf5c6715e587565d1f899bb2e3d8a35
2 years ago

Rebased to master
and added the following:

  • Applied semantic linebreaks to changed paragraphs
  • Moved unrelated typo fixes to their own pull request #1089
  • Fixed inaccurate discussion of the same topic in Unowned directories subpage.
Edited 2 years ago by oturpe

the directory does not belong to the core filesystem package
Maybe even drop "core" here? We don't have a concept of "core packages", but here it sounds like if there was some special meaning.

the directory does not belong to the core filesystem package

Maybe even drop "core" here? We don't have a concept of "core packages", but here it sounds like if there was some special meaning.

Looks good to me.

rebased onto 1e4c5cc81aeaec1a30cd6c28f2d6eaae3acbffc9
2 years ago

the directory does not belong to the core filesystem package

Maybe even drop "core" here? We don't have a concept of "core packages", but here it sounds like if there was some special meaning.

Yes, that was just carried over from the old wording. Dropped.

Redundant, this should either be
"Every directory a package places files into"
or
"Every directory where a package puts files"

("installs" might even be better than places/puts, in either case)

rebased onto 688be1c175e76e89414cc8c7f468c88c5b43c3c1
a year ago

rebased onto 2f664f1
a year ago

Redundant, this should either be
"Every directory a package places files into"
or
"Every directory where a package puts files"

("installs" might even be better than places/puts, in either case)

Thank you for the review.
I went with your second option, and used the term "install" as well.
Edited a year ago by oturpe
Metadata
None
No Tags
Changes Summary 2
+1 -1
file changed
guidelines/modules/ROOT/pages/UnownedDirectories.adoc
+51 -38
file changed
guidelines/modules/ROOT/pages/index.adoc
Powered by Pagure 5.13.3
Documentation • File an Issue • About • SSH Hostkey/Fingerprint
© Red Hat, Inc. and others.