rubygem packaging

[Parag Nemade]

Hi all,
     I am new to ruby package reviewing and to ruby also. I already
got some help from vondruch on rubygem packaging but I also saw some
problems which are not addressed in
http://fedoraproject.org/wiki/Packaging:Ruby#Ruby_Gems

1) I think we need some sample rubygem spec file (which can also
include -doc subpackage)

2) I see most of rubygem packages also create -doc, but I can't find
which files should go this subpackage. I see most gem archive contains
files like README, LICENSE, Rakefile, CHANGES and directories like
tests, examples. I think it should be written on packaging page about
which package should own these files.

3) packaging page says %files should look like
%{gemdir}/gems/%{gemname}-%{version}/
%{gemdir}/cache/%{gemname}-%{version}.gem
%{gemdir}/specifications/%{gemname}-%{version}.gemspec

but most of latest submitted/accepted packages have
%dir %{geminstdir}
%{geminstdir}

4) I don't understand reason behind marking doc files as %doc whereas
I see they are not actually installed under /usr/share/doc. What I
come to know only is that one can search for documentation files using
RPM

5) gem install command is used with --rdoc in spec in latest submissions.

6) If its good practice to have %check in rubygem specs then we should
have it mentioned in packaging page.

7) Is there a case where rubygem package need to used %global macros
ruby_sitelib or ruby_sitearch? If not then we can remove those %global
lines from spec file right?

8) also saw some rubygem packages in fedora which don't have BR:ruby

9) another thing can be added to packaging page that for few rubygem
packages rpmlint is not silent with warning for generated doc as  W:
unexpanded-macro and this can be ignored.

Thanks & Regards,
Parag.

[Vít Ondruch]

Dne 20.4.2011 15:07, Parag N(पराग़) napsal(a):
> Hi all,
>       I am new to ruby package reviewing and to ruby also. I already
> got some help from vondruch on rubygem packaging but I also saw some
> problems which are not addressed in
> http://fedoraproject.org/wiki/Packaging:Ruby#Ruby_Gems
> I think we need some sample rubygem spec file (which can also
>
> include -doc subpackage)

I have tried to upgrade gem2rpm a bit. So if you will use my fork [1], 
the -doc subpackage should be generated by default. Also I have 
extracted the templates out of the code, so they are a bit more readable 
now [2]. May be I should request merge to upstream, but originally I 
planed to spend more time with it :)
> I see most of rubygem packages also create -doc, but I can't find
>
> which files should go this subpackage. I see most gem archive contains
> files like README, LICENSE, Rakefile, CHANGES and directories like
> tests, examples. I think it should be written on packaging page about
> which package should own these files.

This follows general packaging guidelines. The rule is that the base 
package should contain only essential files for execution, the rest 
should go into -doc. This includes Rakefile, testsuite, etc.
> packaging page says %files should look like
>
> %{gemdir}/gems/%{gemname}-%{version}/
> %{gemdir}/cache/%{gemname}-%{version}.gem
> %{gemdir}/specifications/%{gemname}-%{version}.gemspec
>
> but most of latest submitted/accepted packages have
> %dir %{geminstdir}
> %{geminstdir}

This is triggered by creation of the -doc subpackage. Once you decide to 
have -doc subpackage, then you can't include the whole %{geminstdir}, 
but you have to choose what to goes into what package.

I would like to see the -doc package as a requirement, since the 
documentation is typically several times bigger then the gem itself. 
Also I am not sure about others, but I usually prefer to use web 
documentation (rdoc.info).
> I don't understand reason behind marking doc files as %doc whereas
>
> I see they are not actually installed under /usr/share/doc. What I
> come to know only is that one can search for documentation files using
> RPM

There are 2 cases from my POV:

1) You assume that the -doc subpackage contains only documentation, 
therefore marking the files as %doc is not required.
2) In you case, the -doc subpackage can contain also test suite for 
example. In this case, the $ rpm -qd package-doc will show the real 
documentation files without the test suite.

I would like to follow the 2nd approach, but the opinions may differ.
> gem install command is used with --rdoc in spec in latest submissions.

I would like to see --rdoc to be prohibited. It was always default and I 
don't believe it will change in near future.
> If its good practice to have %check in rubygem specs then we should
>
> have it mentioned in packaging page.

The packaging guidelines encourages the test suite execution [3]. 
However I would love to see the ruby guidelines extended by my comments [4].
> Is there a case where rubygem package need to used %global macros
>
> ruby_sitelib or ruby_sitearch? If not then we can remove those %global
> lines from spec file right?

ruby_sitelib is required when package is intended to be used without 
rubygems [5]
> also saw some rubygem packages in fedora which don't have BR:ruby

This is probably wrong, but it is not mentioned in guidelines. Basically 
all packages has BR: rubygems and rubygems requires ruby. But it is not 
as specific as the runtime requirement Requires: ruby(abi) = 1.8

This should be clarified.
> another thing can be added to packaging page that for few rubygem
>
> packages rpmlint is not silent with warning for generated doc as  W:
> unexpanded-macro and this can be ignored.

Or may be rpmlint could be updated?

There is also more issues to cover, such as installation of gem with 
--bindir flag instead of some magic, the gems should be always installed 
in %prep section, etc.

Vit
> Thanks&  Regards,
> Parag.
> _______________________________________________
> ruby-sig mailing list
> [e-mail]
> https://admin.fedoraproject.org/mailman/listinfo/ruby-sig

[1] https://github.com/voxik/gem2rpm/
[2] https://github.com/voxik/gem2rpm/blob/master/templates/fedora.spec.erb
[3] http://fedoraproject.org/wiki/Packaging:Guidelines#Test_Suites
[4] http://fedoraproject.org/wiki/Packaging_talk:Ruby#Testsuite_execution
[5] 
http://fedoraproject.org/wiki/Packaging:Ruby#Packaging_for_Gem_and_non-Gem_u...

[Chris Lalancette]

On 04/21/11 - 05:34:36PM, Vít Ondruch wrote:
> Dne 20.4.2011 15:07, Parag N(पराग़) napsal(a):
> > Hi all,
> >       I am new to ruby package reviewing and to ruby also. I already
> > got some help from vondruch on rubygem packaging but I also saw some
> > problems which are not addressed in
> > http://fedoraproject.org/wiki/Packaging:Ruby#Ruby_Gems
> > I think we need some sample rubygem spec file (which can also
> >
> > include -doc subpackage)
>
> I have tried to upgrade gem2rpm a bit. So if you will use my fork [1], 
> the -doc subpackage should be generated by default. Also I have 
> extracted the templates out of the code, so they are a bit more readable 
> now [2]. May be I should request merge to upstream, but originally I 
> planed to spend more time with it :)

Yeah, please do.  There are already two projects out there called "gem2rpm";
forking into a third is not ideal.

[Vít Ondruch]

Dne 21.4.2011 21:39, Chris Lalancette napsal(a):
> On 04/21/11 - 05:34:36PM, Vít Ondruch wrote:
> > Dne 20.4.2011 15:07, Parag N(पराग़) napsal(a):
> > > Hi all,
> > >        I am new to ruby package reviewing and to ruby also. I already
> > > got some help from vondruch on rubygem packaging but I also saw some
> > > problems which are not addressed in
> > > http://fedoraproject.org/wiki/Packaging:Ruby#Ruby_Gems
> > > I think we need some sample rubygem spec file (which can also
> > >
> > > include -doc subpackage)
> >
> > I have tried to upgrade gem2rpm a bit. So if you will use my fork [1],
> > the -doc subpackage should be generated by default. Also I have
> > extracted the templates out of the code, so they are a bit more readable
> > now [2]. May be I should request merge to upstream, but originally I
> > planed to spend more time with it :)
>
> Yeah, please do.  There are already two projects out there called "gem2rpm";
> forking into a third is not ideal.

Done: https://github.com/lutter/gem2rpm/pull/1

Vit

[Mo Morsi]

On 04/21/2011 11:34 AM, Vít Ondruch wrote:
> > I see most of rubygem packages also create -doc, but I can't find
> >
> > which files should go this subpackage. I see most gem archive contains
> > files like README, LICENSE, Rakefile, CHANGES and directories like
> > tests, examples. I think it should be written on packaging page about
> > which package should own these files.
>
> This follows general packaging guidelines. The rule is that the base 
> package should contain only essential files for execution, the rest 
> should go into -doc. This includes Rakefile, testsuite, etc.

There is also the rule about staying as close as possible to the
upstream package to consider as well.

http://fedoraproject.org/wiki/PackageMaintainers/WhyUpstream
> > packaging page says %files should look like
> >
> > %{gemdir}/gems/%{gemname}-%{version}/
> > %{gemdir}/cache/%{gemname}-%{version}.gem
> > %{gemdir}/specifications/%{gemname}-%{version}.gemspec
> >
> > but most of latest submitted/accepted packages have
> > %dir %{geminstdir}
> > %{geminstdir}
>
> This is triggered by creation of the -doc subpackage. Once you decide to 
> have -doc subpackage, then you can't include the whole %{geminstdir}, 
> but you have to choose what to goes into what package.
>
> I would like to see the -doc package as a requirement, since the 
> documentation is typically several times bigger then the gem itself. 
> Also I am not sure about others, but I usually prefer to use web 
> documentation (rdoc.info).

There are packages though with little documentation, and I'd think it
makes more sense to ship those with the package itself instead of a
whole nother sub-package.

So my vote is to still leave it up to the packager but it's not a huge
deal for me.
> > I don't understand reason behind marking doc files as %doc whereas
> >
> > I see they are not actually installed under /usr/share/doc. What I
> > come to know only is that one can search for documentation files using
> > RPM
>
> There are 2 cases from my POV:
> You assume that the -doc subpackage contains only documentation,
>
> therefore marking the files as %doc is not required.
> 2) In you case, the -doc subpackage can contain also test suite for 
> example. In this case, the $ rpm -qd package-doc will show the real 
> documentation files without the test suite.

Marking files as %doc helps from the perspective that you can pass in
--excludedocs   to "rpm -i".

This is useful for installing packages on systems w/ limited disk space,
or without the documentation dependencies (man for example),
> I would like to follow the 2nd approach, but the opinions may differ.
> > gem install command is used with --rdoc in spec in latest submissions.
>
> I would like to see --rdoc to be prohibited. It was always default and I 
> don't believe it will change in near future.

Whats the reasoning behind prohibiting it?
> > If its good practice to have %check in rubygem specs then we should
> >
> > have it mentioned in packaging page.
>
> The packaging guidelines encourages the test suite execution [3]. 
> However I would love to see the ruby guidelines extended by my comments [4].

Correct, by default all ruby packages have to comply to the Fedora
guidelines in addition to the Ruby guidelines.

-Mo

[Vít Ondruch]

Dne 26.4.2011 19:31, Mo Morsi napsal(a):
> > > packaging page says %files should look like
> > >
> > > %{gemdir}/gems/%{gemname}-%{version}/
> > > %{gemdir}/cache/%{gemname}-%{version}.gem
> > > %{gemdir}/specifications/%{gemname}-%{version}.gemspec
> > >
> > > but most of latest submitted/accepted packages have
> > > %dir %{geminstdir}
> > > %{geminstdir}
> >
> > This is triggered by creation of the -doc subpackage. Once you decide to
> > have -doc subpackage, then you can't include the whole %{geminstdir},
> > but you have to choose what to goes into what package.
> >
> > I would like to see the -doc package as a requirement, since the
> > documentation is typically several times bigger then the gem itself.
> > Also I am not sure about others, but I usually prefer to use web
> > documentation (rdoc.info).
>
> There are packages though with little documentation, and I'd think it
> makes more sense to ship those with the package itself instead of a
> whole nother sub-package.
>
> So my vote is to still leave it up to the packager but it's not a huge
> deal for me.

I just like to see change the default, the rest is of course up to 
packager and reviewer.
> > > I don't understand reason behind marking doc files as %doc whereas
> > >
> > > I see they are not actually installed under /usr/share/doc. What I
> > > come to know only is that one can search for documentation files using
> > > RPM
> >
> > There are 2 cases from my POV:
> > You assume that the -doc subpackage contains only documentation,
> >
> > therefore marking the files as %doc is not required.
> > 2) In you case, the -doc subpackage can contain also test suite for
> > example. In this case, the $ rpm -qd package-doc will show the real
> > documentation files without the test suite.
>
> Marking files as %doc helps from the perspective that you can pass in
> --excludedocs   to "rpm -i".
>
> This is useful for installing packages on systems w/ limited disk space,
> or without the documentation dependencies (man for example),

Mamoru should comment on this since he is the fan of not marking files 
as a %doc in -doc subpackage.
> > I would like to follow the 2nd approach, but the opinions may differ.
> > > gem install command is used with --rdoc in spec in latest submissions.
> >
> > I would like to see --rdoc to be prohibited. It was always default and I
> > don't believe it will change in near future.
>
> Whats the reasoning behind prohibiting it?

Is it better to be explicit and more wordy or to be implicit? 
Configuration on convention?

The reasoning for me is the same as not including the %clean section 
(http://fedoraproject.org/wiki/Packaging:Guidelines#.25clean), not 
executing "|rm -rf %{buildroot}|" on top of install, etc.

Vit

[Mo Morsi]

On 04/27/2011 04:56 AM, Vít Ondruch wrote:
> > Marking files as %doc helps from the perspective that you can pass in
> > --excludedocs   to "rpm -i".
> >
> > This is useful for installing packages on systems w/ limited disk space,
> > or without the documentation dependencies (man for example),
>
> Mamoru should comment on this since he is the fan of not marking files
> as a %doc in -doc subpackage.

Ah srry should've clarified. This isn't for the -doc subpackage per-se
(I agree it doesn't make a whole lot of sense to mark the files as %doc
there), but rather for the main package.

%doc allows you to separate the documentation from the main
functionality in the main package without creating a documentation
subpackage.

Its just up to the packager to choose which one they think will keep
their package(s) more organized and simpler.

-Mo