Skip to content

docs(config): add configuration guides#6790

Open
317787106 wants to merge 8 commits into
tronprotocol:release_v4.8.2from
317787106:feature/config_comment
Open

docs(config): add configuration guides#6790
317787106 wants to merge 8 commits into
tronprotocol:release_v4.8.2from
317787106:feature/config_comment

Conversation

@317787106
Copy link
Copy Markdown
Collaborator

@317787106 317787106 commented May 20, 2026

What does this PR do?

  1. Rewrites reference.conf comments — every parameter now has an inline comment describing its purpose, valid range, and unit. The file is the authoritative default-value reference for all node operators and contributors.

  2. Slims down config.conf — removes the large duplicated comment blocks that belonged in reference.conf, leaving only the parameters whose shipped defaults intentionally differ from reference.conf and the minimal comments users need to act on.

  3. Fixes default values for three under-specified parameters:

    • node.rpc.maxConcurrentCallsPerConnection: Integer.MAX_VALUE0 (0 = no limit)
    • node.rpc.maxConnectionIdleInMillis / maxConnectionAgeInMillis: changed to 0 (0 = no limit)
    • node.dns.maxMergeSize: 15; changeThreshold: 0.80.1 (align with actual recommended values)
  4. Adds two documentation files under docs/:

    • configuration.md — user-facing guide: explains the reference.conf / config.conf two-layer system, how to start a node with a config file, and the most common configuration sections with examples.
    • configuration-conventions.md — developer-facing guide: covers ConfigBeanFactory auto-binding rules, the camelCase naming requirement, nesting depth limits, the four-step checklist for adding a new parameter, special type handling (List<String>, human-readable sizes), and backward-compatibility patterns.

Why are these changes required?

config.conf previously duplicated most of reference.conf's comment content, making it hard to maintain and causing users to question which file to trust. Meanwhile reference.conf lacked inline documentation for many parameters. There was also no written guide explaining the two-layer config system or the conventions developers must follow when extending it, leading to inconsistencies (non-camelCase keys, missing reference.conf entries, etc.).

This PR has been tested by

  • Unit Tests
  • Manual Testing

@github-actions github-actions Bot requested a review from halibobo1205 May 20, 2026 09:45
@317787106 317787106 changed the title doc(config): add documents of how to change config file as necessary docs(config): add documents of how to change config file as necessary May 20, 2026
@317787106 317787106 changed the title docs(config): add documents of how to change config file as necessary docs(config): add configuration guides May 20, 2026
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