Two points:

rpmlint warns about all sorts of things. rpmlint is not intended to check everything that is in the Fedora packaging guidelines, nor does it check only things which are in those guidelines. That doesn't mean that something is good practice just because it is not forbidden by a guideline.

In general, you can include pretty much whatever you like in documentation. However, there are (at least) two situations to avoid. First, consider why you want things to be executable. If users should be running them, install them where they can be run, not buried under /usr/share/doc/whatever. Second, you don't want the documentation causing dependencies that the package would not otherwise have. I believe rpm will autogenerate dependencies from executable documentation.

rpmlint warns about all sorts of things. rpmlint is not intended to check everything that is in the Fedora packaging guidelines, nor does it check only things which are in those guidelines. That doesn't mean that something is good practice just because it is not forbidden by a guideline.

In other words, executables under %doc do not block a package review. Am I right?

In general, you can include pretty much whatever you like in documentation. However, there are (at least) two situations to avoid. First, consider why you want things to be executable. If users should be running them, install them where they can be run, not buried under /usr/share/doc/whatever.

Examples are documentation. Thus they should go into %doc. I think there is no discussion where to install such files. (Do you know about better place?)

My concern was why rpmlint does not like executables in %doc.

Second, you don't want the documentation causing dependencies that the package would not otherwise have. I believe rpm will autogenerate dependencies from executable documentation.

If this is why rpmlint warns, rpmlint should note it (`executables trigger unneeded dependencies').

Well, I'd block a package review on executables in %doc, at least until the other points I raised were considered.

I mean, if you expect people to run them, you should put them in /usr/bin. If you don't expect people to run them, why do they need to be executable at all? It seems pretty simple to me, especially for a scripting language where you just run "perl /path/to/foo.pl" and it runs.

As to your question of why rpmlint does something, you should keep in mind that FPC does not maintain rpmlint and cannot necessarily explain why it checks what it checks. It's used for at least one other rpm-based distribution which may have different guidelines and, to be honest, the set of things it complains about is not always in line with the Fedora packaging guidelines. That doesn't mean that it's not a useful tool, but if you are expecting to find justification for everything it complains about in the guidelines, you will be disappointed.

However, looking at the rpmlint sources, I'm seeing the following:

'doc-file-dependency',
'''An included file marked as %doc creates a possible additional dependency in
the package. Usually, this is not wanted and may be caused by eg. example
scripts with executable bits set included in the package's documentation.''',

I assume that's the rpmlint complaint you are referring to; it seems pretty explicit to me.

I would agree here. You can package them, just mark them -x if they're not in the $PATH.

"%doc files must not have executable permissions" passes (+1:5, 0:0, -1:1)

Provided what was decided, it would be consequent if rpm was changed to[[BR]]

• automatically chmod -x all %doc'ed files[[BR]]
  or[[BR]]
• to refuse building packages containing executable %doc

BTW: a quick check over current F14+updates lists approx. 3300 files from ca. 50 packages violating this new rule.

Announce text:

The guidelines have been updated to indicate that %doc files must not have executable permissions.

https://fedoraproject.org/wiki/Packaging:Guidelines#Documentation

After feedback, I think we should consider altering the guideline to this:

"Files marked as documentation must not cause additional dependencies that aren't satisfied by the package itself or its dependency chain as it would be if none of its files marked as documentation were included in the package. One simple way to ensure this is to remove all executable permissions from %doc files (chmod -x)."

"Files marked as documentation must not cause the package to pull in more dependencies than it would without the documentation. One simple way to ensure this is to remove all executable permissions from %doc files (chmod -x)."

action abadger1999's minimal wording approved (+1:5, 0:0, -1:1)

Bonus question: How should I package examples into separate sub-package demanding new dependencies?

AFAIK the files should go into /usr/share/doc/%{name}-example-%{version}, effectively %doc dir. However I cannot just install them without %doc macro as the %doc macro makes magic with the directory (removing, recreating, copying from builddir, marking as documentation). Note the %doc is usually required to accompany license wording.

I guess there exists a %files section macro to mark documentation file manually (like lang(code) for translations), however it seems deeply hidden in tons of outdated RPM documentation.

the deeply hidden tag is %doc + full (not relative) path

%files
%doc %{_libdir}/blah/foo.txt

Second revision committed and announced.