Templated spec.files ships non-runtime files, breaking downstream packaging on every addition

[ogajduse]

Problem

Gems generated/maintained via this template (observed in auth-sanitizer,
anonymous_loader, version_gem, snaky_hash, likely others) ship a fixed
set of non-runtime files in spec.files / spec.extra_rdoc_files:

• certs/, sig/ (signing certs, RBS signatures — not needed for a working install)
• CITATION.cff, CODE_OF_CONDUCT.md, CONTRIBUTING.md, FUNDING.md,
  RUBOCOP.md, SECURITY.md (repo governance/community-health files)
• License files (LICENSE.md, and now MIT.md as of the recent license split)

None of these are required to require or run the gem. Distro packagers (RPM/DEB)
have to maintain an explicit %files/.install list mirroring this set, and every
time the template adds a new file to the manifest, every downstream package build
breaks with no warning — the packager only finds out when rpmbuild fails.

Real-world impact

The recent split of LICENSE.md into a summary + new top-level MIT.md broke RPM
builds for all four gems above at once, since none of their spec files referenced
the new file:

error: Installed (but unpackaged) file(s) found: /usr/share/gems/gems/<GEM>-<VERSION>/MIT.md

Fixed downstream in:

• Update rubygem-auth-sanitizer to 0.2.3 theforeman/foreman-packaging#13729 (auth-sanitizer)
• Update rubygem-anonymous_loader to 0.1.3 theforeman/foreman-packaging#13731 (anonymous_loader)
• Update rubygem-version_gem to 1.1.14 theforeman/foreman-packaging#13733 (version_gem)
• Update rubygem-snaky_hash to 2.0.7 theforeman/foreman-packaging#13735 (snaky_hash)

This is the same class of problem previously raised (for a different root cause —
git ls-files) in mdub/clamp#125 and
rkerberos/rkerberos#44: every non-runtime file shipped
in the gem is a file every distro packager has to explicitly track, and template
changes propagate breakage across every gem using the template simultaneously.

Proposed solution

Trim the templated spec.files/extra_rdoc_files to what's actually needed to
run the gem: lib/, a single license file, README.md. Move governance/CI files
(CITATION.cff, CODE_OF_CONDUCT.md, CONTRIBUTING.md, FUNDING.md,
RUBOCOP.md, SECURITY.md, certs/, sig/) out of the published package —
they serve repo browsing on GitHub/GitLab, not installed gems, and don't need to
ship to every consumer.

If the manifest does need to grow (e.g. the MIT.md split), it'd help downstream
packagers to call it out explicitly in the gem's changelog as a packaging-affecting
change, since it's not visible in the gem's public API diff.

Happy to submit a patch if useful.

[pboling]

@ogajduse Thanks so much for explaining this! I had no idea this was an issue. I will ensure the template spec.files is restricted to files that are required for the package itself.

I would very much appreciate your feedback on the PR to reduce the set of included files, so I will ping you there when ready.

Aside: We should probably work on adding some rules to rubocop-packaging to help raise awareness of this.
Aside#2: IIRC the default bundle gem generator creates a gem with the git ls-files problem. I am not on speaking terms with the Ruby team so I won't touch that with a ten-foot pole, but it is worth fixing there (though perhaps not a fight worth engaging in).

[pboling]

Oh, also this is the legacy repo for the gem. I preparing the release of the new gem, and it is now part of a mono-repo here:
https://github.com/structuredmerge/structuredmerge-ruby/tree/main/gems/kettle-jem - so I will move this issue there.
I will be archiving the legacy non-monorepos soon.

[pboling]

Fixed in #39

[pboling]

@ogajduse I will be releasing updated patch versions of the gems that revert to the old set of files (though retaining the switch from LICENSE.txt to LICENSE.md.