feat(ci,config): add comment coverage gate for reference.conf#6810
Open
bladehan1 wants to merge 2 commits into
Open
feat(ci,config): add comment coverage gate for reference.conf#6810bladehan1 wants to merge 2 commits into
bladehan1 wants to merge 2 commits into
Conversation
Add check_reference_comments.py, a line-oriented Python script that enforces every 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. genesis.block array elements (assets, witnesses) carry field-level inline comments derived from the existing block descriptions; there is no genesis.block exemption.
bladehan1
changed the title
Kingsp2026
approved these changes
Jun 2, 2026
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
5 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.
What does this PR do?
Adds a comment-coverage CI gate for
reference.confand annotates all previously undocumented configuration keys.Changes
.github/scripts/check_reference_comments.py(new, 358 lines, zero runtime dependencies)#///) comment or a non-blank comment on the immediately preceding line.rate.limiterentries).--listflag prints every key with its status (commented/dedup/missing) for local debugging.::errorannotations withline N: key.+=, triple-quoted strings, bare URLs) and explains why each is low-risk forreference.conf..github/workflows/pr-check.yml(+6 lines)check_reference_conf.py(key-format / depth / port-uniqueness) gate.continue-on-error.common/src/main/resources/reference.confcommitteeblock includes the/wallet/getchainparametersAPI key name andProposalTypeID for each governance parameter.Why are these changes required?
reference.confis the primary configuration reference for node operators. Before this change most keys had no explanation, forcing operators to read source code. There was no CI enforcement either, 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.conf→OK(exit 0)python3 .github/scripts/check_reference_conf.py common/src/main/resources/reference.conf→OK: 290 keys, all lowerCamelCase, depth <= 5, service ports unique(exit 0)check_reference_comments.py --listoutput verified: 252 commented, 118 dedup, 0 missingcommitteeblock comments cross-checked against live mainnet/wallet/getchainparametersAPI response andProposalUtil.ProposalTypeenum in source — all 42 ProposalType IDs and API key names confirmed correct.helper/test_reference_conf/run.sh— 41/41 passed (14 comment-coverage fixtures + 17 key-format fixtures + realreference.confsmoke tests)Extra details
#///) are fully transparent to Typesafe Config and pyhocon — no runtime behaviour is affected.reference.conf(quoted keys,+=, triple-quoted strings) are documented as known limitations in the script docstring.