Skip to content

Refresh REFERENCE.md in every committing sync session - #117

Open
silug wants to merge 1 commit into
simp:mainfrom
silug:reference-md-every-sync
Open

silug wants to merge 1 commit into
simp:mainfrom
silug:reference-md-every-sync

Conversation

@silug

@silug silug commented Oct 8, 2026

Copy link
Copy Markdown
Contributor

openvox-strings releases change the generated REFERENCE.md: 7.2.0 drops the trailing blank line that 7.1.0 wrote. The pupmod PR tests run rake validate:strings, so every PR from a session that didn't list generate_reference_md failed the REFERENCE.md freshness check, over drift the session didn't cause. The 20261002-openvox9-ga PRs are an example.

Change

  • plans/init.pp: if a session's stages include git_commit_changes but not generate_reference_md, the plan adds the stage. No config changes are needed; the next run of any session picks it up.
  • tasks/generate_reference_md: new only_changed parameter, which the plan sets when it added the stage itself. It skips a module that has no REFERENCE.md (so one is never created) and a module with no uncommitted changes from earlier stages (so the stage never pulls a repo into a session for drift alone). The result reports skipped with the reason.
  • Sessions that list the stage keep the old behavior and regenerate REFERENCE.md in every pupmod.
  • README: documents the implicit stage under "Inspecting pipeline stages".

One limitation: a re-run onto an existing feature branch whose changes are already committed has a clean tree, so the implicit stage skips it. Listing the stage covers that case.

Testing

  • New BoltSpec plan spec (spec/plans/generate_reference_md_stage_spec.rb): implicit with only_changed: true for a committing session, only_changed: false when the stage is listed, and not run for a session that doesn't commit.
  • New task specs for only_changed: regenerates in a changed repo, skips a clean repo, and doesn't create a missing REFERENCE.md.
  • rspec: 252 examples, 0 failures. Plan specs: 34 examples, 0 failures. bolt plan show puppetsync loads.

🤖 Generated with Claude Code

openvox-strings releases change the generated REFERENCE.md (7.2.0
dropped the trailing blank line), and the pupmod PR tests fail any PR
whose REFERENCE.md doesn't match. A session that didn't list the
generate_reference_md stage then opened PRs that failed over drift they
didn't cause.

The sync plan now adds generate_reference_md to any session whose
stages include git_commit_changes. Run implicitly, the task gets the new
only_changed parameter and skips modules without a REFERENCE.md and
modules that no earlier stage changed, so it never creates a
REFERENCE.md or widens a session to repos it had no other reason to
touch. Listing the stage keeps the old behavior: regenerate in every
pupmod in the session.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant