Automatic javadoc subpackage genration

[Stanislav Ochotnicky]

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-...
[2]
http://inputvalidation.blogspot.com/2011/11/automatic-javadoc-subpackage-...
[3] http://git.fedorahosted.org/git?p=javapackages.git;a=summary (generate_javadoc
branch)

--
Stanislav Ochotnicky <sochotnicky(a)redhat.com&gt;
Software Engineer - Base Operating Systems Brno

PGP: 7B087241
Red Hat Inc.                               http://cz.redhat.com

[Ville Skyttä]

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.

[Stanislav Ochotnicky]

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(a)redhat.com&gt;
Software Engineer - Base Operating Systems Brno

PGP: 7B087241
Red Hat Inc.                               http://cz.redhat.com

[David Walluck]

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?

[Stanislav Ochotnicky]

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_L...

--
Stanislav Ochotnicky <sochotnicky(a)redhat.com&gt;
Software Engineer - Base Operating Systems Brno

PGP: 7B087241
Red Hat Inc.                               http://cz.redhat.com

[Aleksandar Kurtakov]

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(a)redhat.com&gt;
>  Software Engineer - Base Operating Systems Brno
>  
>  PGP: 7B087241
>  Red Hat Inc.                               http://cz.redhat.com

[David Walluck]

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_L...;.
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.