ci: add comment coverage gate for reference.conf#6805
Closed
bladehan1 wants to merge 1 commit into
Closed
Conversation
Add check_reference_comments.py, a line-oriented Python script that enforces every non-genesis.block key in reference.conf carries an inline or immediately-preceding comment. Wire it into pr-check.yml as a new CI step directly after the existing key-format gate. Annotate all previously undocumented keys in reference.conf with inline # / // comments. The committee block now includes the /wallet/getchainparameters API key name and ProposalType ID for each governance parameter.
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
1 participant
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.
What does this PR do?
Adds a CI comment-coverage gate for
reference.confand documents all previously undocumented configuration keys.New script
.github/scripts/check_reference_comments.py— a zero-dependency, line-oriented Python 3 script that enforces every non-genesis.blockkey inreference.confcarries either an inline (#///) comment or a comment on the immediately preceding line. Array-element keys are deduplicated (only the first occurrence is checked). Fails with::errorGHA annotations listing every offendingline N: key.CI step in
.github/workflows/pr-check.yml— runs the new gate directly after the existingcheck_reference_conf.py(key-format / port-uniqueness) step, so future PRs that add undocumented keys are blocked automatically.reference.conf annotations — all previously undocumented keys now carry inline comments. The
committeeblock includes the/wallet/getchainparametersAPI key name andProposalTypeID (verified against both the live mainnet API andProposalUtil.ProposalTypeenum) for every governance parameter.Why are these changes required?
reference.confis the primary configuration reference for node operators. Before this change, the majority of keys had no explanation, forcing operators to read source code to understand parameters. There was also no CI enforcement, so new keys could be merged without documentation.This PR has been tested by:
python3 .github/scripts/check_reference_comments.py common/src/main/resources/reference.confreturnsOK(exit 0)check_reference_conf.py(pyhocon-based key-format gate) still passes after thereference.confchanges/wallet/getchainparametersAPI andProposalUtil.ProposalTypeenumFollow up
strip_quoted,strip_comments, stack-frame tracking). A follow-up PR could extract a sharedhocon_scan.pyhelper to avoid drift.Extra details
genesis.blockkeys are exempt from the comment requirement (private-chain operators customise these freely).pBFTExpireNum,allowReceiptsMerkleRoot,allowNewRewardAlgorithm— have noProposalTypeentry (private-chain / deprecated governance); their comments reflect this without a#NID.