Changes/UnversionedDocdirs

From FedoraProject

< Changes(Difference between revisions)
Jump to: navigation, search
(Detailed Description: Add info about %{_pkgdocdir})
(Detailed Description: _pkgdocdir pushing to f18-updates)
 
(3 intermediate revisions by 3 users not shown)
Line 19: Line 19:
 
== Current status ==
 
== Current status ==
 
* Targeted release: [[Releases/20 | Fedora 20 ]]  
 
* Targeted release: [[Releases/20 | Fedora 20 ]]  
* Last updated: 2013-07-15
+
* Last updated: 2013-08-08
 
<!-- After the change proposal is accepted by FESCo, tracking bug is created in Bugzilla and linked to this page  
 
<!-- After the change proposal is accepted by FESCo, tracking bug is created in Bugzilla and linked to this page  
 
Bugzilla states meaning as usual:
 
Bugzilla states meaning as usual:
Line 28: Line 28:
 
CLOSED as NEXTRELEASE -> change is completed and verified and will be delivered in next release under development
 
CLOSED as NEXTRELEASE -> change is completed and verified and will be delivered in next release under development
 
-->
 
-->
* Tracker bug: <will be assigned by the Wrangler>
+
* Tracker bug: https://bugzilla.redhat.com/show_bug.cgi?id=993551 [https://bugzilla.redhat.com/show_bug.cgi?id=998579 #998579]
  
 
== Detailed Description ==
 
== Detailed Description ==
Line 34: Line 34:
 
Change the per package documentation directory in /usr/share/doc to unversioned, just containing the package's name (previously it contained both the package's name and its version). rpmbuild already has support for this, by setting the %_docdir_fmt macro to %{name} we cover most of the cases. Other cases can be grepped through from package specfiles/patches -- grepping for _docdir, _defaultdocdir, usr/share/doc and _datadir.*doc should catch almost everything. Packages for which multiple versions are intended to be installed need to be changed to install their docs into appropriately versioned subdirs, for example explicitly using the previous NAME-VERSION scheme. Some of these cases, if unaddressed, will also manifest themselves as build failures due to files not found at expected locations.
 
Change the per package documentation directory in /usr/share/doc to unversioned, just containing the package's name (previously it contained both the package's name and its version). rpmbuild already has support for this, by setting the %_docdir_fmt macro to %{name} we cover most of the cases. Other cases can be grepped through from package specfiles/patches -- grepping for _docdir, _defaultdocdir, usr/share/doc and _datadir.*doc should catch almost everything. Packages for which multiple versions are intended to be installed need to be changed to install their docs into appropriately versioned subdirs, for example explicitly using the previous NAME-VERSION scheme. Some of these cases, if unaddressed, will also manifest themselves as build failures due to files not found at expected locations.
  
A helper macro, %{_pkgdocdir} has been added to F20's redhat-rpm-config. It points to the main package's documentation directory. It can be used also with earlier distro versions for example by conditionally redefining it like:
+
A helper macro, %{_pkgdocdir} has been added to F20, F19, and F18 redhat-rpm-config. It points to the main package's documentation directory. It can be used also with earlier distro versions for example by conditionally redefining it like:
  
 
     %{!?_pkgdocdir: %global _pkgdocdir %{_docdir}/%{name}-%{version}}
 
     %{!?_pkgdocdir: %global _pkgdocdir %{_docdir}/%{name}-%{version}}

Latest revision as of 04:38, 11 September 2013

Contents

[edit] Unversioned Docdirs

[edit] Summary

Install package specific documentation to an unversioned subdir in /usr/share/doc.

[edit] Owner

[edit] Current status

[edit] Detailed Description

Change the per package documentation directory in /usr/share/doc to unversioned, just containing the package's name (previously it contained both the package's name and its version). rpmbuild already has support for this, by setting the %_docdir_fmt macro to %{name} we cover most of the cases. Other cases can be grepped through from package specfiles/patches -- grepping for _docdir, _defaultdocdir, usr/share/doc and _datadir.*doc should catch almost everything. Packages for which multiple versions are intended to be installed need to be changed to install their docs into appropriately versioned subdirs, for example explicitly using the previous NAME-VERSION scheme. Some of these cases, if unaddressed, will also manifest themselves as build failures due to files not found at expected locations.

A helper macro, %{_pkgdocdir} has been added to F20, F19, and F18 redhat-rpm-config. It points to the main package's documentation directory. It can be used also with earlier distro versions for example by conditionally redefining it like:

   %{!?_pkgdocdir: %global _pkgdocdir %{_docdir}/%{name}-%{version}}

Packages referring to their doc dir only once may want to do it for example like (for a hypothetical --docdir option):

   --docdir=%{?_pkgdocdir}%{!?_pkgdocdir:%{_docdir}/%{name}-%{version}}

[edit] Benefit to Fedora

By having the documentation directories unversioned, they and the files in them become inherently easier/stabler to bookmark, cross-reference from other docs, Systemd unit Documentation= etc. Doing so also makes Fedora more consistent with other major distributions that already do this (at least Debian, Mandriva, openSUSE, and Ubuntu at time of writing).

[edit] Scope

  • Proposal owners: take care of having the %_docdir_fmt macro set to %{name} in rpm or redhat-rpm-config, grep through package specfiles and patches identifying cases needing special attention.
  • Other developers: see if their package explicitly refers to a NAME-VERSION subdir in /usr/share/doc, and change those to NAME.
  • Release engineering: mass rebuild is required after the %_docdir_fmt macro change.
  • Policies and guidelines: all documentation referring to NAME-VERSION subdirs in /usr/share/doc needs to be changed to NAME instead.

[edit] Upgrade/compatibility impact

No technical upgrade impact, just documentation.

[edit] How To Test

Installed packages apart from ones for which multiple versions are intended to be installed in parallel should have their documentation installed into an unversioned /usr/share/doc/NAME (not NAME-VERSION) directory.

[edit] User Experience

Better documentation bookmarkability and cross-referenceability (links are less likely to break between package upgrades), familiarity to users accustomed to other major distributions.

[edit] Dependencies

rpm configuration in the rpm package itself, or redhat-rpm-config.

[edit] Contingency Plan

  • Contingency mechanism: revert the %_docdir_fmt change and NAME-VERSION -> NAME changes
  • Contingency deadline: beta release
  • Blocks release? No

[edit] Documentation

N/A

[edit] Release Notes

Per package documentation is now installed into unversioned /usr/share/doc/NAME directories. Previously the directory contained the package's version in addition to its name.