Skip to content

Add a REFERENCE.md freshness check to pr_tests.yml (bundle exec rake validate:strings) #46

Description

@silug

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.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions