Summary
Nothing in the baseline .github/workflows/pr_tests.yml verifies that REFERENCE.md is
current, so it silently goes stale whenever class/defined-type parameters, custom
types/providers, or Puppet functions change. CLAUDE.md tells contributors to regenerate
it, but CI never enforces it.
Proposed fix
Add a step (or job) running the task voxpupuli-test already ships:
- run: 'bundle exec rake validate:strings'
Why this task
validate:strings comes from voxpupuli-test
(lib/voxpupuli/test/rake/validate.rb), which every module already depends on via
simp-rake-helpers:
desc 'validate REFERENCE.md if it exists'
task :strings do
if File.exist?('REFERENCE.md')
Rake::Task['strings:validate:reference'].invoke
end
end
It delegates to strings:validate:reference from openvox-strings, which generates into
a Tempfile, compares against the committed REFERENCE.md, and exits 1 with
"REFERENCE.md is outdated; to regenerate: bundle exec rake strings:generate:reference".
Two properties that matter:
- Read-only. It does not touch the working tree.
- No-ops when there is no
REFERENCE.md — safe for provider-only modules such as
puppet-gpasswd, whose reference is header-only pending the openvox-strings provider
markdown work.
Also: converge the 12 repos already doing this by hand
These already have a REFERENCE.md freshness job, but hand-rolled as
rake strings:generate:reference followed by git diff --exit-code -- REFERENCE.md:
pupmod-simp-acpid, pupmod-simp-aide, pupmod-simp-at, pupmod-simp-auditd,
pupmod-simp-autofs, pupmod-simp-clamav, pupmod-simp-compliance_markup,
pupmod-simp-cron, pupmod-simp-crypto_policy, pupmod-simp-dconf,
pupmod-simp-deferred_resources, pupmod-simp-pki
That variant overwrites REFERENCE.md in the checkout and depends on git state to detect
drift. They should be converted to validate:strings so there is one form fleet-wide
rather than two.
Optional consolidation
voxpupuli-test already aggregates:
task validate: ['validate:ruby', 'syntax', 'metadata_lint', 'validate:strings']
No simp repo currently runs rake validate — the workflows invoke rake syntax and
rake metadata_lint as separate steps. Replacing those two with a single
bundle exec rake validate would pick up validate:ruby and validate:strings for free.
Worth considering, but a larger change than adding the one step; rake lint
(puppet-lint) stays separate either way.
Blocked on
#42 — needs puppetsync working again before this can be rolled out.
Summary
Nothing in the baseline
.github/workflows/pr_tests.ymlverifies thatREFERENCE.mdiscurrent, so it silently goes stale whenever class/defined-type parameters, custom
types/providers, or Puppet functions change.
CLAUDE.mdtells contributors to regenerateit, but CI never enforces it.
Proposed fix
Add a step (or job) running the task
voxpupuli-testalready ships:Why this task
validate:stringscomes fromvoxpupuli-test(
lib/voxpupuli/test/rake/validate.rb), which every module already depends on viasimp-rake-helpers:It delegates to
strings:validate:referencefromopenvox-strings, which generates intoa
Tempfile, compares against the committedREFERENCE.md, and exits 1 with"REFERENCE.md is outdated; to regenerate: bundle exec rake strings:generate:reference".Two properties that matter:
REFERENCE.md— safe for provider-only modules such aspuppet-gpasswd, whose reference is header-only pending the openvox-strings providermarkdown work.
Also: converge the 12 repos already doing this by hand
These already have a
REFERENCE.md freshnessjob, but hand-rolled asrake strings:generate:referencefollowed bygit diff --exit-code -- REFERENCE.md:pupmod-simp-acpid,pupmod-simp-aide,pupmod-simp-at,pupmod-simp-auditd,pupmod-simp-autofs,pupmod-simp-clamav,pupmod-simp-compliance_markup,pupmod-simp-cron,pupmod-simp-crypto_policy,pupmod-simp-dconf,pupmod-simp-deferred_resources,pupmod-simp-pkiThat variant overwrites
REFERENCE.mdin the checkout and depends on git state to detectdrift. They should be converted to
validate:stringsso there is one form fleet-widerather than two.
Optional consolidation
voxpupuli-testalready aggregates:No simp repo currently runs
rake validate— the workflows invokerake syntaxandrake metadata_lintas separate steps. Replacing those two with a singlebundle exec rake validatewould pick upvalidate:rubyandvalidate:stringsfor free.Worth considering, but a larger change than adding the one step;
rake lint(puppet-lint) stays separate either way.
Blocked on
#42 — needs
puppetsyncworking again before this can be rolled out.