docs: generate op-batcher flag reference from source, keyed to finalized releases#21847
Merged
Conversation
Replace the hand-transcribed op-batcher flag catalog (pinned to v1.10.0, missing all six throttle.pid-* flags and the newer txmgr/signer flags) with a table generated from the flag definitions the binary actually registers. - docs/public-docs/scripts/gen-flags: Go generator walking op-batcher's composed urfave/cli Flags slice via the DocGenerationFlag accessors, so the output matches --help semantics; emits an MDX snippet with a do-not-edit header and a provenance line naming the release tag recorded in manifest.json (op-batcher/v1.16.11). - docs/public-docs/snippets/generated/op-batcher-flags.mdx: generated output, 87 flags (3 required, 84 optional). - batcher-configuration.mdx: import the generated snippet; drop the 'options are from the --help in v1.10.0' disclaimer; keep hand-written framing prose and add a throttling narrative that surfaces op-batcher/throttling.md. - .github/workflows/docs-flag-drift.yml: regenerate + git diff --exit-code, path-filtered to op-batcher/flags/ and the docs paths; failure message includes the regen command. - CODEOWNERS: explicit entries for the generator, generated snippets, and the drift workflow; ownership model in the gen-flags README. Tracks ethereum-optimism/solutions#957 Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01EBBBR8m2V8LjzMvuG7Go2L
op-batcher's --compressor usage string embeds compressor.KindKeys, which is collected from map iteration and therefore ordered randomly on every process start (in op-batcher --help itself, not just here). Sort that one option list in the generator so regeneration is byte-stable and the drift check cannot flake; document the source-side one-line fix (sorting KindKeys at init) as a follow-up. Tracks ethereum-optimism/solutions#957 Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01EBBBR8m2V8LjzMvuG7Go2L
…check The drift workflow fetched mise with an unpinned 'curl https://mise.run | sh', so the job's own tooling was the only unpinned fetch in it. Use the same SHA-pinned jdx/mise-action (mise 2026.2.2) the repo's docker-build-prep composite action already uses, which also handles config trust on the runner. Co-Authored-By: Claude <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01EBBBR8m2V8LjzMvuG7Go2L
claude
Bot
added
docs-improver
Wiz Scan Summary
To detect these findings earlier in the dev lifecycle, try using Wiz Code VS Code Extension. |
![wiz-0f98cca50a[bot]](https://avatars.githubusercontent.com/u/58791460?s=60&v=4){kind=small}
Contributor
|
Preview deployment for your docs. Learn more about Mintlify Previews.
|
Address SAST findings on the flag-reference generator: - Create the output directory with 0o750 and write snippets with 0o640 instead of 0o755/0o644. Git does not store these mode bits, so this only tightens permissions on the CI runner's disk; committed output is unaffected. - Resolve the docs dir once and route every read/write path through a pathUnder helper that cleans the joined path and errors out if it escapes the docs root. The paths come from in-repo constants, not user input, so this is defense in depth. Regenerated output is byte-identical. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01EBBBR8m2V8LjzMvuG7Go2L
Contributor
|
Preview deployment for your docs. Learn more about Mintlify Previews.
|
…automation Replace the GitHub Actions drift-check workflow with a release-driven flow: the snippet is generated at the finalized op-batcher release tag recorded in manifest.json and refreshed when a new non-rc tag is published, enforced by a review-gated Mintlify docs automation on a schedule plus local runs. Add a -check mode to the generator for local verification, and drop the dedicated CODEOWNERS entries — the existing /docs/public-docs/ rule already covers every path in the pipeline. Co-Authored-By: Claude <noreply@anthropic.com>
claude
Bot
changed the title
Contributor
Author
|
Paste-ready Mintlify docs-automation config for the release-keyed refresh (replaces the removed GitHub Actions drift workflow):
Additional prompt: |
sbvegan
approved these changes
Jul 17, 2026
sbvegan
enabled auto-merge
July 17, 2026 05:03
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Requested by Matthew Cruz · Slack thread
Tracks ethereum-optimism/solutions#957
What
Slice B1 of the Truth-from-Source docs program: replace the hand-transcribed op-batcher flag catalog with a table generated from source, regenerated only when a new finalized op-batcher release is published.
docs/public-docs/scripts/gen-flags/): walks the composedop-batcher/flags.Flagsslice (including the op-service families appended ininit(): rpc, log, metrics, pprof, txmgr, altda) via urfave/cli'sDocGenerationFlagaccessors, so output matches--helpsemantics. Emitssnippets/generated/op-batcher-flags.mdxwith a do-not-edit header and a provenance line for the release tag recorded inmanifest.json(op-batcher/v1.16.11, the latest finalized tag). A-checkmode verifies the committed snippet matches generated output without rewriting it.throttle.pid-*flags plus the newer txmgr/signer flags; it also carried wrong defaults (e.g.--active-sequencer-check-durationis5s, not2m0s).chain-operators/reference/batcher-configuration.mdx: imports the snippet; the "options are from the--helpin v1.10.0" disclaimer is gone; hand-written prose kept around the table, with a throttling narrative that surfacesop-batcher/throttling.md.op-batcher/v*tag is published — not on everydevelopchange. Enforcement runs as a review-gated Mintlify docs automation on a weekly schedule (paste-ready config in the PR comments), plus local generator runs. Procedure indocs/public-docs/scripts/gen-flags/README.md. No GitHub Actions workflow and no new CODEOWNERS entries: everything lives underdocs/public-docs/, already owned by @ethereum-optimism/solutions via the existing CODEOWNERS rule.Notes for reviewers
docs.jsonchange;guides/configuration/batcher.mdxuntouched.--compressoroption list:compressor.KindKeysis map-ordered and random on every process start, inop-batcher --helpitself. Follow-up proposed: sortKindKeysat init (one line inop-batcher/compressor/compressors.go).Reviewer checklist
op-batcher/flagsatop-batcher/v1.16.11throttle.pid-*flags presentPart of the docs-improver program — see
projects/docs-improver/README.mdin ethereum-optimism/solutions.🤖 Drafted by the docs-improver agent — review before merge.
🤖 Generated with Claude Code
https://claude.ai/code/session_01EBBBR8m2V8LjzMvuG7Go2L
Generated by Claude Code