Hi list,
We have already discussed automatic javadoc subpackage generation during our SIG meeting few months back [1]. At the time we had two issues with it: * it didn't handle licensing (javadoc has to have license of its own if upstream provides it or require main package) * we'd still have to copy javadocs into %_javadocdir
Yesterday I decided to look into this and created a bit more convoluted macro with more options. See [2] or [3] for details. Basically we try to do everything automatically but allow packagers to modify behaviour of the macro: * Specify non-standard location where we can find license (until we add it to standard paths macro looks into) * Specify directory where apidocs are generated (we default to maven-generated target/site/apidocs) * Allow packager to override adding of "Requires: %{name}.." into javadoc (we do this if we don't find license file). This is useful when upstream has no separate license file
Also, I hooked into RPM so the javadocs are copied to %{_javadocdir} automatically without any intervention needed from packager.
As far as I know this should cover most use-cases, but I am looking for feedback before proposing changes to the guidelines.
[1] http://meetbot.fedoraproject.org/fedora-meeting/2011-06-01/java-sig.2011-06-... [2] http://inputvalidation.blogspot.com/2011/11/automatic-javadoc-subpackage-gen... [3] http://git.fedorahosted.org/git?p=javapackages.git;a=summary (generate_javadoc branch)
-- Stanislav Ochotnicky sochotnicky@redhat.com Software Engineer - Base Operating Systems Brno
PGP: 7B087241 Red Hat Inc. http://cz.redhat.com
On 11/03/2011 06:36 PM, Stanislav Ochotnicky wrote:
As far as I know this should cover most use-cases, but I am looking for feedback before proposing changes to the guidelines.
It seems to lack a mechanism for specifying dependencies, e.g. to other *-javadoc packages when crosslinking.
Excerpts from Ville Skyttä's message of Fri Nov 04 18:17:01 +0100 2011:
On 11/03/2011 06:36 PM, Stanislav Ochotnicky wrote:
As far as I know this should cover most use-cases, but I am looking for feedback before proposing changes to the guidelines.
It seems to lack a mechanism for specifying dependencies, e.g. to other *-javadoc packages when crosslinking.
Good point. I guess it shouldn't be a problem to add another variable to customize this.
-- Stanislav Ochotnicky sochotnicky@redhat.com Software Engineer - Base Operating Systems Brno
PGP: 7B087241 Red Hat Inc. http://cz.redhat.com
On 11/03/2011 12:36 PM, Stanislav Ochotnicky wrote:
- Allow packager to override adding of "Requires: %{name}.." into javadoc (we do this if we don't find license file). This is useful when upstream has no separate license file
First, the License is supposed to be in the RPM header. Second, that is already a Fedora policy. Third, most distros allow a common licenses packages that has the full license text.
You want the documentation to require the full set of binaries just to get the license file?
Excerpts from David Walluck's message of Fri Nov 04 21:39:13 +0100 2011:
On 11/03/2011 12:36 PM, Stanislav Ochotnicky wrote:
- Allow packager to override adding of "Requires: %{name}.." into javadoc (we do this if we don't find license file). This is useful when upstream has no separate license file
First, the License is supposed to be in the RPM header. Second, that is already a Fedora policy. Third, most distros allow a common licenses packages that has the full license text.
If I read this correctly then you misunderstand our current licensing guidelines[1]. Please read that small part before doing anything else.
It effectively means this: a) *IF* source tarball has license, it has to be installed as %doc b) In that case *all* sub-packages that *do not* require main package have to include that license file as well.
Now we have several situations: a) Package has license in one of standard licenses
- we generate javadoc, find the license file, install it. No requires on main package. Ergo no problem
b) Package has license, but in place we can't find
- if there would be no modifications the macro would add Requires: %{name}-%{version} etc. to javadoc to satisfy above guidelines.
After your suggestion and talking with Alex, I've come to conclusion that it will be better to bail with error message in this case. This will force packager to do one of these things: %global __javadoc_license path/to/license/inside/tarball or
c) Package has no license in separate file In this case packager will define %global __javadoc_no_license t
And we will ignore licensing completely. Does this work for you? I guess I could prepare a few example spec files to better explain different cases.
You want the documentation to require the full set of binaries just to get the license file?
It would be the right thing to do from packaging guidelines point of view. There can be no chance of automatically generating javadoc package without license file if upstream provides this, since that would be against guidelines. But bailing and forcing packager to either set path to license file or tell us to ignore licensing works just as well.
[1] https://fedoraproject.org/wiki/Packaging/LicensingGuidelines#Subpackage_Lice...
-- Stanislav Ochotnicky sochotnicky@redhat.com Software Engineer - Base Operating Systems Brno
PGP: 7B087241 Red Hat Inc. http://cz.redhat.com
On 13:20:47 Monday 07 November 2011 Stanislav Ochotnicky wrote:
Excerpts from David Walluck's message of Fri Nov 04 21:39:13 +0100 2011:
On 11/03/2011 12:36 PM, Stanislav Ochotnicky wrote:
Allow packager to override adding of "Requires: %{name}.." into
javadoc (we do this if we don't find license file). This is useful when upstream has no separate license file
First, the License is supposed to be in the RPM header. Second, that is already a Fedora policy. Third, most distros allow a common licenses packages that has the full license text.
If I read this correctly then you misunderstand our current licensing guidelines[1]. Please read that small part before doing anything else.
It effectively means this: a) *IF* source tarball has license, it has to be installed as %doc b) In that case *all* sub-packages that *do not* require main package have to include that license file as well.
Now we have several situations: a) Package has license in one of standard licenses
- we generate javadoc, find the license file, install it. No requires
on main package. Ergo no problem
b) Package has license, but in place we can't find
- if there would be no modifications the macro would add Requires:
%{name}-%{version} etc. to javadoc to satisfy above guidelines.
After your suggestion and talking with Alex, I've come to conclusion that it will be better to bail with error message in this case. This will force packager to do one of these things: %global __javadoc_license path/to/license/inside/tarball or
c) Package has no license in separate file In this case packager will define %global __javadoc_no_license t
And we will ignore licensing completely. Does this work for you? I guess I could prepare a few example spec files to better explain different cases.
You want the documentation to require the full set of binaries just to get the license file?
It would be the right thing to do from packaging guidelines point of view.
I have to make it clear that there are no guidelines that are stating that a subpackage should require the main one for the license file. The guidelines require the packager to do their work to set the javadoc properly not to require the main package blindly.
Alex
There can be no chance of automatically generating javadoc package without license file if upstream provides this, since that would be against guidelines. But bailing and forcing packager to either set path to license file or tell us to ignore licensing works just as well.
[1] https://fedoraproject.org/wiki/Packaging/LicensingGuidelines#Subpackage_Li censing
-- Stanislav Ochotnicky sochotnicky@redhat.com Software Engineer - Base Operating Systems Brno
PGP: 7B087241 Red Hat Inc. http://cz.redhat.com
On 11/07/2011 06:22 AM, Alexander Kurtakov wrote:
I have to make it clear that there are no guidelines that are stating that a subpackage should require the main one for the license file. The guidelines require the packager to do their work to set the javadoc properly not to require the main package blindly.
It's either that or include it as %doc in the javadoc package itself, according to what I was just linked to https://fedoraproject.org/wiki/Packaging/LicensingGuidelines#Subpackage_Licensing. I don't know who wrote that or how it possibly satisfies any legal requirement better than other methods---especially since following that section on the wiki is the `License: field' section that I also mentioned.
What is gained by placing a license file in every package? If the goal is just to make sure that the license text is present on the system, this could be achieved in other ways if it's a standard license. If the packager determines that is it one of the standard licenses, I still don't understand what is gained by copying it over and over. I hope that the policy is based on a specific legal requirement.
java-devel@lists.fedoraproject.org
-
Aleksandar Kurtakov -
David Walluck -
Stanislav Ochotnicky -
Ville Skyttä