docs: add AGENTS.md and reorganize project documentation by SeriousCoding789 · Pull Request #6871 · tronprotocol/java-tron

SeriousCoding789 · 2026-07-13T03:59:39Z

What does this PR do?

Adds AGENTS.md, a build, test and architecture guide for AI coding assistants and new contributors.
Adds a Documentation index to the README.
Documents the p2p module: adds it to the module layout in AGENTS.md and to the modular introduction (en / zh), links its README from the Documentation index, and lists p2p-standalone.jar under Executables.
Moves the protobuf protocol document and the metrics changelog into docs/, and marks the two 2022 protocol copies as superseded.
Brings the protobuf protocol document in line with the .proto files: missing fields and enum values, the six Stake 2.0 contracts, and the removal of TransactionSign.
Adds Super Representative private-key security notes to docs/configuration.md.
Moves the java.lang.Math check into .github/scripts/check_math_usage.sh, run by both math-check.yml and the AGENTS.md self-check.
Removes the unused CodeClimate and Sonar configuration and the .dockerignore file.

Why are these changes required?

There was no single guide to building, testing and the rules CI enforces; several CI gates were undocumented.
A self-check copied into the docs drifts from CI; sharing one script keeps them identical.
Existing guides were not linked from the README, and the outdated protocol copies did not say so.
The module lists and the README predated the p2p module.
The protocol document had fallen behind the .proto files since 2023, mostly around Stake 2.0.
.codeclimate.yml and sonar-project.properties are no longer used by CI.

This PR has been tested by:

Unit Tests: N/A, documentation and CI script only.
Manual Testing: checked AGENTS.md against the build configuration and sources, ran the pre-commit checklist commands, and confirmed all moved paths and links resolve. check_math_usage.sh reports nothing on the repository and flags sample files using java.lang.Math.abs(-1), import java.lang.Math; and a static import. A script comparing every message and enum in the protocol document with the .proto files reports no differences. The p2p entries were checked against the build configuration, and the :p2p Checkstyle tasks referenced in AGENTS.md pass.

Follow up

None.

Extra details

None.

abn2357 · 2026-07-14T04:21:22Z

Two issues and one optional naming nit as below, please consider whether modifications are required.:

Reconcile the remaining Sonar references

This PR removes .codeclimate.yml and sonar-project.properties because they are no longer used by CI, but Sonar-related references remain:
- framework/build.gradle:3 still applies org.sonarqube.
- CONTRIBUTING.md:150 says that the Sonar scanner is automatically triggered for pull requests.
- CONTRIBUTING.md:161 requires contributions to pass the Sonar scanner test.
Please update CONTRIBUTING.md to reflect the current CI process.
Fix the relative source link after moving the metrics changelog

After moving METRICS_CHANGELOG.md into docs/, the link to common/src/main/java/org/tron/common/prometheus/ on line 22 now resolves to the non-existent path:

docs/common/src/main/java/org/tron/common/prometheus/

Please change the link target from:

common/src/main/java/org/tron/common/prometheus/

to:

../common/src/main/java/org/tron/common/prometheus/
[Nit] Consider using kebab-case consistently

Most files under docs/ use kebab-case, while metrics_changelog.md uses snake_case. Consider renaming it to metrics-changelog.md for consistency with names such as protobuf-protocol-document.md.

SeriousCoding789 · 2026-07-14T05:56:35Z

Two issues and one optional naming nit as below, please consider whether modifications are required.:

Reconcile the remaining Sonar references
This PR removes .codeclimate.yml and sonar-project.properties because they are no longer used by CI, but Sonar-related references remain:

framework/build.gradle:3 still applies org.sonarqube.

CONTRIBUTING.md:150 says that the Sonar scanner is automatically triggered for pull requests.

CONTRIBUTING.md:161 requires contributions to pass the Sonar scanner test.

Please update CONTRIBUTING.md to reflect the current CI process.

Fix the relative source link after moving the metrics changelog
After moving METRICS_CHANGELOG.md into docs/, the link to common/src/main/java/org/tron/common/prometheus/ on line 22 now resolves to the non-existent path:
docs/common/src/main/java/org/tron/common/prometheus/
Please change the link target from:
common/src/main/java/org/tron/common/prometheus/
to:
../common/src/main/java/org/tron/common/prometheus/

[Nit] Consider using kebab-case consistently
Most files under docs/ use kebab-case, while metrics_changelog.md uses snake_case. Consider renaming it to metrics-changelog.md for consistency with names such as protobuf-protocol-document.md.

very good suggestion, will fix all.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

- Note the build fails fast on a JDK/arch mismatch - Scope the lint helper comment to framework main - Fix the generated-protobuf source path (core/, api/ subdirs) - Add the platform module (arch-specific source sets) to the layout - List both plugins jars (Toolkit, ArchiveManifest)

start.sh and start.sh.simple are not changed on this branch, so keep their guide and their rows in the README Executables table.

- Move the java.lang.Math check into .github/scripts/check_math_usage.sh and run it from both math-check.yml and AGENTS.md, so the self-check also flags fully qualified calls and imports. - Document the protoLint rule that the zero value of a new enum starts with UNKNOWN_. - Use an existing test method in the single-test example and drop protocol from the Checkstyle module list.

- Add the fields and enum values missing from Account, AccountResource, Transaction.Result, TransactionInfo, ResourceReceipt, InternalTransaction, SmartContract, ReasonCode and HelloMessage, with descriptions, and drop TransactionSign, which no longer exists. - Document the six Stake 2.0 contracts and the FreezeV2 / UnFreezeV2 messages. - State that the .proto files are the source of truth in the document, README, AGENTS.md and the outdated copies under protocol/src/main/protos.

- README: list p2p-standalone.jar in the executables table. - AGENTS.md and the modular introduction (en/zh): drop the libp2p version, the DNS providers, the tree:// URL format and how common exposes the module, since those can change.

* release_v4.8.3: feat(framework): remove --keystore-factory support from FullNode (tronprotocol#6978) refactor(proto): remove unused proto discover definition (tronprotocol#7014) fix(config): close resource streams (tronprotocol#7002) refactor(crypto): remove unused SM2 and SM3 (tronprotocol#6999) feat(plugins): backfill section bloom (tronprotocol#6973) refactor(api): remove dead WalletExtension gRPC service and config (tronprotocol#6975) refactor(framework): decouple Manager from TronJsonRpcImpl (tronprotocol#6990) refactor(api): replace response copy wrappers with Jetty content count (tronprotocol#6982) update a new version. version name:GreatVoyage-v4.8.2.2-1-gf3e81404fe,version code:18830 (tronprotocol#7008) feat: improve node stability and execution efficiency (tronprotocol#7007)

* release_v4.8.3: feat(crypto): harden ECKey validation (tronprotocol#6996) fix(config): fail startup on invalid DNS publish parameters (tronprotocol#7019) fix(jsonrpc): normalize error responses and fatal handling (tronprotocol#6985) fix(jsonrpc): handle null parameters consistently (tronprotocol#6984) refactor(trie): remove unused RLP utilities (tronprotocol#6991)

…alue same as reference.conf

0xbigapple

LGTM

warku123

LGTM

github-actions Bot requested review from 317787106 and halibobo1205 July 13, 2026 03:59

bombaycubza-svg approved these changes Jul 13, 2026

View reviewed changes

Little-Peony force-pushed the fix_readme branch from 5ce2274 to f70cc65 Compare July 14, 2026 05:58

317787106 approved these changes Jul 14, 2026

View reviewed changes

lvs0075 added this to the GreatVoyage-v4.8.2 milestone Jul 14, 2026

halibobo1205 added the topic:documentation label Jul 14, 2026

halibobo1205 approved these changes Jul 14, 2026

View reviewed changes

halibobo1205 reviewed Jul 14, 2026

View reviewed changes

Comment thread framework/build.gradle

halibobo1205 self-requested a review July 14, 2026 10:24

SeriousCoding789 changed the base branch from release_v4.8.2 to develop July 16, 2026 05:56

halibobo1205 removed this from the GreatVoyage-v4.8.2 milestone Jul 17, 2026

SeriousCoding789 changed the title ~~docs: reorganize documentation and remove stale CI configs~~ docs: add AGENTS.md and reorganize project documentation Jul 20, 2026

Little-Peony force-pushed the fix_readme branch from 07dfda5 to 0ca52e5 Compare July 20, 2026 03:14

tronprotocol deleted a comment Jul 23, 2026

Little-Peony and others added 12 commits September 14, 2026 15:27

docs(readme): add Documentation section linking guides and protocol doc

0098981

docs(config): add super-representative private-key security notes

90dea2c

docs: move protocol document into docs/ with a shorter name

6dea9d6

docs: move metrics changelog into docs/ and link from README

b661d06

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

docs: mark outdated protobuf protocol copies as superseded

5d565d6

chore(ci): remove unused CodeClimate and Sonar configs

6f1f3e9

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

delete .dockerignore

21f7d6c

modify chinese

f6ec27a

docs: drop stale Sonar references and fix metrics changelog link

8334a03

chore: remove unused Sonar entries from verification-metadata

0369ec4

docs: add AGENTS.md for AI assistants and contributors

c7011ba

SeriousCoding789 mentioned this pull request Sep 28, 2026

fix: harden start.sh #7003

Open

Little-Peony added 2 commits September 28, 2026 14:36

docs: restore shell.md and start script entries in README

3c07622

start.sh and start.sh.simple are not changed on this branch, so keep their guide and their rows in the README Executables table.

0xbigapple approved these changes Sep 29, 2026

View reviewed changes

317787106 approved these changes Sep 29, 2026

View reviewed changes

0xbigapple approved these changes Sep 29, 2026

View reviewed changes

Little-Peony added 4 commits September 29, 2026 18:32

Merge branch 'release_v4.8.3' into fix_readme

6b28b14

add libp2p related in doc

0db602d

docs: reword the p2p-standalone.jar entry in README

3303a35

bombaycubza-svg approved these changes Oct 2, 2026

View reviewed changes

halibobo1205 reviewed Oct 10, 2026

View reviewed changes

Comment thread AGENTS.md Outdated

Little-Peony added 2 commits October 12, 2026 14:04

docs: correct the revoking session rule in AGENTS.md

170ce1f

SeriousCoding789 requested review from 0xbigapple, 317787106 and halibobo1205 October 12, 2026 06:10

halibobo1205 reviewed Oct 12, 2026

View reviewed changes

Comment thread AGENTS.md Outdated

Little-Peony added 2 commits October 12, 2026 14:55

docs: state the JDK 17 requirement for ErrorProne in AGENTS.md

8410af9

halibobo1205 approved these changes Oct 13, 2026

View reviewed changes

warku123 reviewed Oct 13, 2026

View reviewed changes

Comment thread AGENTS.md Outdated

Comment thread AGENTS.md Outdated

0xbigapple reviewed Oct 13, 2026

View reviewed changes

Comment thread docs/protobuf-protocol-document.md Outdated

Little-Peony added 2 commits October 13, 2026 14:38

feature: add openHistoryQueryWhenLiteFN in config.conf with default v…

adfa0af

…alue same as reference.conf

docs: correct checkstyle gate, module deps and contract version notes

2d8b6bb

0xbigapple approved these changes Oct 13, 2026

View reviewed changes

warku123 approved these changes Oct 13, 2026

View reviewed changes

317787106 approved these changes Oct 13, 2026

View reviewed changes

kuny0707 merged commit a901f85 into tronprotocol:release_v4.8.3 Oct 13, 2026
15 of 16 checks passed

Navigation Menu

Repository navigation

docs: add AGENTS.md and reorganize project documentation - #6871

docs: add AGENTS.md and reorganize project documentation#6871
kuny0707 merged 39 commits into
tronprotocol:release_v4.8.3from
Little-Peony:fix_readme

SeriousCoding789 commented Jul 13, 2026 •

edited

Loading

Uh oh!

abn2357 commented Jul 14, 2026

Uh oh!

SeriousCoding789 commented Jul 14, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

0xbigapple left a comment

Uh oh!

warku123 left a comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

10 participants

Conversation

SeriousCoding789 commented Jul 13, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

abn2357 commented Jul 14, 2026

Uh oh!

SeriousCoding789 commented Jul 14, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

0xbigapple left a comment

Choose a reason for hiding this comment

Uh oh!

warku123 left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

10 participants

SeriousCoding789 commented Jul 13, 2026 •

edited

Loading