Are test files documentation?

[Mamoru Tasaka]

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