I was reviewing a ruby package today, and while reviewing noticed that %{geminstdir}/tests was not marked as %doc. I checked my specs and on some it is and on other it is not.
What is the official policy? If there isn't one, can we decide on how to do this? Also, how should spec be handled? Some developers prefer spec over test.
Right now for documentation files we have:
%{geminstdir}/ ri rdoc examples Rakefile History README License
stahnma
Michael Stahnke wrote, at 08/11/2010 07:43 AM +9:00:
I was reviewing a ruby package today, and while reviewing noticed that %{geminstdir}/tests was not marked as %doc. I checked my specs and on some it is and on other it is not.
What is the official policy? If there isn't one, can we decide on how to do this? Also, how should spec be handled? Some developers prefer spec over test.
Right now for documentation files we have:
%{geminstdir}/ ri rdoc examples Rakefile History README License
stahnma
Generally, files which are used only for test purpose are even _not packaged_ into final binary rpm. - For example, almost all perl module related tarball have perl scripts for test purpose under t/ directory and usually perl module related srpms are requested to enable some test program in %check (mostly $ make test). However such test scripts under t/ directory are not packaged into final binary rpms. - Also there are not a few tarballs based on general autotools (i.e. autoconf/automake/etc) which have test/ directory and in which $ make test executes some test program. In such cases reviewer usually requests to add %check section, however usually test/ directory is not included into final binary rpm.
So based on the consistency with other srpms in Fedora, files under tests/ or spec/ directory should be _removed_ from binary rpms, because - these directories are used only for test purpose - not needed on runtime - and actually not "documentation".
However what is different for gem based rpms here is that "gem install" tries to install tests/ or spec/ directory by default, even though these files are actually not needed on runtime. So when I review gem based srpms, usually - while I don't say tests/ or spec/ file should be removed from binary rpm, - I (always) say these directories should be marked as %doc to indicate that these are actually "not needed". - And I even say that these directories should be separated into -doc subpackage and only files which are really needed on runtime (and some document files like "README COPYING" and so on) should be in main package. - Then I say that marking %doc attribute in -doc subpackage is redundant because the rpm name ("-doc") already indicates that the rpm is for documentation.
Regards, Mamoru
I certainly wouldn't want to remove tests or specs from packages. They often contain the best examples of how to use a specific gem. Making them all into a separate package for -doc seems like it would create a lot more packages, and I can't think of many situations where I wouldn't want to install the primary and doc package, as gem itself does. You can tell gem not to install ri/rdoc but spec/test is still there. Marking them as %doc seems reasonable.
stahnma
Michael Stahnke wrote, at 08/12/2010 12:10 AM +9:00:
I certainly wouldn't want to remove tests or specs from packages. They often contain the best examples of how to use a specific gem. Making them all into a separate package for -doc seems like it would create a lot more packages, and I can't think of many situations where I wouldn't want to install the primary and doc package, as gem itself does.
Generally I want to install only the files which are actually needed, and want to check which is really needed.
Also in many cases gems rpms are needed for dependency issue only (i.e. actually to run some application, like alexandria or fantastic which I maintain). In such cases people don't want to install such "unneeded" files.
And, while one gem base rpm itself may be small, usually tests/ or spec/ directory have compatible size compared to lib/ + bin/ directory, and with generated ri/rdoc files the size of total "documentation" files usually becomes larger than that of the files needed for runtime.
So IMO splitting tests/ spec/ directories + generated ri/rdoc files into -doc subpackge is preferred and I have always requested so. Only "developers" will want to install such files ("usual" people don't want to install "-devel" package for running applications).
You can tell gem not to install ri/rdoc
... when installing gem by themselves. When creating gem based rpm, we usually create ri/rdoc (from rubygems 1.3.5+).
but spec/test is still there. Marking them as %doc seems reasonable.
stahnma
Regards, Mamoru
Ok, I see your point. I am normally developing with ruby, so I didn' think about the normal application install.
Should we then say that ri/rdoc/examples/test/spec go into a -doc package when they are over a certain size or always?
I'd just like to get some consistency here.
Also when we decide we should work with the packaging guys to get the wiki page updated for ruby packages.
stahnma
Michael Stahnke wrote, at 08/12/2010 01:02 AM +9:00:
Ok, I see your point. I am normally developing with ruby, so I didn' think about the normal application install.
Should we then say that ri/rdoc/examples/test/spec go into a -doc package when they are over a certain size or always?
My opinion is we should create -doc subpackage when they are large to some extent, especially when such files have compatible or larger size than those of files needed for runtime.
I'd just like to get some consistency here.
Also when we decide we should work with the packaging guys to get the wiki page updated for ruby packages.
stahnma
Something like the following proposal * Creating -doc subpackage - Usually ruby gem based rpm installs rdoc/ri document files under %{gemdir}/doc/%{gemname}-%{version}. Also many ruby gem based rpm installs some additional files under %{geminstdir} which are not needed on runtime and are needed for development purpose only or checking the gem like: - Rakefile - spec/ directory - test/ directory - examples/ directory If the total size of these files is compatible or enough larger than that of the files needed for runtime, -doc subpackage should be created and these files should be moved into -doc subpackage.
Any comments welcome.
Regards, Mamoru
On Wed, Aug 11, 2010 at 12:41 PM, Mamoru Tasaka mtasaka@ioa.s.u-tokyo.ac.jp wrote:
Michael Stahnke wrote, at 08/12/2010 01:02 AM +9:00:
Ok, I see your point. I am normally developing with ruby, so I didn' think about the normal application install.
Should we then say that ri/rdoc/examples/test/spec go into a -doc package when they are over a certain size or always?
My opinion is we should create -doc subpackage when they are large to some extent, especially when such files have compatible or larger size than those of files needed for runtime.
I'd just like to get some consistency here.
Also when we decide we should work with the packaging guys to get the wiki page updated for ruby packages.
stahnma
Something like the following proposal
- Creating -doc subpackage
- Usually ruby gem based rpm installs rdoc/ri document files under %{gemdir}/doc/%{gemname}-%{version}. Also many ruby gem based rpm installs some additional files under %{geminstdir} which are not needed on runtime and are needed for development purpose only or checking the gem like: - Rakefile - spec/ directory - test/ directory - examples/ directory If the total size of these files is compatible or enough larger than that of the files needed for runtime, -doc subpackage should be created and these files should be moved into -doc subpackage.
Any comments welcome.
I like the proposal, but would like a definitive way to know when to make a -doc package or not to.
It would be spectacular if we could make some edits to gem2rpm to do this by default.
stahnma
ruby-sig@lists.fedoraproject.org
-
Mamoru Tasaka -
Michael Stahnke