https://fedoraproject.org/wiki/Packaging:Guidelines#Documentation
Proposed addition to the guidelines:
Independent documentation -doc packages typically don't require the base package. It should be possible to install documentation without having to install a program and all its dependencies.
Rationale: Recently, in package review requests, I've seen packagers apply https://fedoraproject.org/wiki/Packaging:Guidelines#Requiring_Base_Package also to -doc packages. And there are packages in the collection, which do that, too. This is a hindrance, especially if one only wants to peruse the documentation or install API documentation for remote developing. Of course, an exception to this is documentation in a special format, which can only be viewed within an application.
Thoughts?
Perhaps meaning of "Independent" (documentation) is ambiguous.
Additionally, I think that many -doc subpackage requires main package is because -doc installs documents under the directory the main package owns: i.e. the main package has some "important" documents in one directory and the rest documents are included in -doc subpackage, and -doc uses the same directory. Usually I don't want to duplicate ownership of the same directory for this reason (so usually make -doc subpackage require main package), however I don't object to your thought so much. I think it is better to write explicitly that duplicating directory ownership is allowed (if your new proposition is accepted).
Regards, Mamoru
On Mon, 10 Jun 2013 16:40:56 +0900, Mamoru Tasaka wrote:
Proposed addition to the guidelines:
Independent documentation -doc packages typically don't require the base package. It should be possible to install documentation without having to install a program and all its dependencies.
Perhaps meaning of "Independent" (documentation) is ambiguous.
"Separate documentation -doc packages ..."?
The word should refer to documentation that has been split off into a separate -doc package (because it's not required at run-time and not at install-time either).
I think it is better to write explicitly that duplicating directory ownership is allowed (if your new proposition is accepted).
That's covered by this already: https://fedoraproject.org/wiki/Packaging:Guidelines#The_directory_is_owned_b...
On Mon, Jun 10, 2013 at 12:40 AM, Mamoru Tasaka mtasaka@fedoraproject.org wrote:
https://fedoraproject.org/wiki/Packaging:Guidelines#Documentation
Proposed addition to the guidelines:
Independent documentation -doc packages typically don't require the base package. It should be possible to install documentation without having to install a program and all its dependencies.
Rationale: Recently, in package review requests, I've seen packagers apply https://fedoraproject.org/wiki/Packaging:Guidelines#Requiring_Base_Package also to -doc packages. And there are packages in the collection, which do that, too. This is a hindrance, especially if one only wants to peruse the documentation or install API documentation for remote developing. Of course, an exception to this is documentation in a special format, which can only be viewed within an application.
Thoughts?
There's two things I remember from the past:
* We want (need?) license files to be present in either the subpackage or a Require'd main package. So the draft should mention that. * I remember a discussion about this where rationale for including the Requires was because the API could change and you'd want to make sure that the documentation that you had installed matched with the API of the library you have installed. I think this is a tradeoff and I personally incline towards your rationale being the stronger one.
I'd like to see the rationale about wanting to browse the documentation locally for remote developing added to the Draft. If you'd be willing to open up an FPC ticket with an updated draft we can vote on it at the next meeting.
Additionally, I think that many -doc subpackage requires main package is because -doc installs documents under the directory the main package owns: i.e. the main package has some "important" documents in one directory and the rest documents are included in -doc subpackage, and -doc uses the same directory. Usually I don't want to duplicate ownership of the same directory for this reason (so usually make -doc subpackage require main package), however I don't object to your thought so much. I think it is better to write explicitly that duplicating directory ownership is allowed (if your new proposition is accepted).
This is a further wrinkle. It may deserve its own section. To just use something like:
%files %doc LICENSE
%files doc %doc LICENSE API_docs/*
doesn't run afoul of this and seems pretty straightforward to me.
When you want to place the docs in the documentation directory of the main package, there's other things you have to do besides manage package ownership. IIRC, you end up having to manage the documentation directory explicitly yourself and *cannot* use the %doc macro.
%install mkdir -p %{buildroot}%{_docdir}/%{name}%{version}-%{release} cp -pr README LICENSE api_doc %{buildroot}%{_docdir}/%{name}%{version}-%{release}/
%files %{_docdir}/%{name}%{version}-%{release}/ %{_docdir}/%{name}%{version}-%{release}/README %{_docdir}/%{name}%{version}-%{release}/LICENSE
%files doc %{_docdir}/%{name}%{version}-%{release}/ %{_docdir}/%{name}%{version}-%{release}/LICENSE %{_docdir}/%{name}%{version}-%{release}/api_doc
More complex and easy to get wrong (Someone please correct me if this has changed or I'm flat out wrong. It's been a while since I played around with this)
Anyhow, the added complexity is why I think this might deserve its own section.
-Toshio
packaging@lists.fedoraproject.org