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)

download() now prints a notice and returns non-zero; release files must be fetched and verified manually. It returns instead of exiting so that restart() still completes when rebuildManifest reaches it.

This reverts commit 800f084.

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.

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

0xbigapple reviewed Sep 17, 2026

View reviewed changes

Comment thread AGENTS.md Outdated

Little-Peony added 5 commits September 17, 2026 17:22

docs: qualify --tests examples with the framework module

6d79908

docs: correct the actuator registration rule in AGENTS.md

1b0690f

docs: use the fully qualified StrictMathWrapper name

016e727

docs: reference the real ISession type in the DB rule

d785afb

docs: correct the lite-fullnode query rule in AGENTS.md

ff4ca6c

0xbigapple reviewed Sep 17, 2026

View reviewed changes

Comment thread AGENTS.md Outdated

docs: point commit convention to CONTRIBUTING.md

92ff475

0xbigapple reviewed Sep 17, 2026

View reviewed changes

Comment thread README.md

docs: drop Script from the README executables header

d6dfa94

0xbigapple reviewed Sep 17, 2026

View reviewed changes

Comment thread AGENTS.md Outdated

0xbigapple reviewed Sep 17, 2026

View reviewed changes

Comment thread AGENTS.md Outdated

docs: correct test parallelism and actuator fee rules in AGENTS.md

f457100

SeriousCoding789 added this to the GreatVoyage-v4.8.3 milestone Sep 22, 2026

SeriousCoding789 added this to java-tron Sep 22, 2026

Little-Peony added 3 commits September 23, 2026 11:10

chore: restore start.sh and start.sh.simple

642e539

fix: disable download in start.sh

800f084

download() now prints a notice and returns non-zero; release files must be fetched and verified manually. It returns instead of exiting so that restart() still completes when rebuildManifest reaches it.

revert: disable download in start.sh

6d40041

This reverts commit 800f084.

SeriousCoding789 mentioned this pull request Sep 28, 2026

fix: time out idle HTTP connections and 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

Navigation Menu

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

docs: add AGENTS.md and reorganize project documentation#6871
SeriousCoding789 wants to merge 33 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!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

8 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!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

8 participants

SeriousCoding789 commented Jul 13, 2026 •

edited

Loading