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/architecture guide for AI coding assistants and new contributors, covering the pre-commit checklist that mirrors the CI gates, the module dependency rules, and the invariants that must not be broken.
Adds a Documentation index to the README linking every guide.
Moves the protobuf protocol document and the metrics changelog into docs/ with consistent kebab-case names; marks two 2022-era protocol copies as superseded.
Adds Super-Representative private-key security notes to the configuration guide.
Removes obsolete deployment scripts (start.sh, start.sh.simple, shell.md) — they are no longer maintained; node deployment is covered by the Docker image and is handed over to tron-deployment.
Removes unused CI configuration (.codeclimate.yml, sonar-project.properties, stale Sonar entries in the dependency verification metadata) and the .dockerignore file.

Why are these changes required?

No single entry point told contributors — or AI assistants — how to build and test the project, how the modules relate, or which constraints CI enforces. Several CI gates (the java.lang.Math prohibition, the reference.conf schema and comment checks, dependency verification) were undocumented, so a contributor could only discover them by failing a build.
Several guides existed but were unlinked from the README; the protocol document and metrics changelog cluttered the repository root and the proto tree.
Two 2022-era protocol copies gave no indication that they were stale.
The configuration guide never warned that a plaintext block-producing key can leak through file permissions or be committed to Git.
The deployment scripts had drifted out of maintenance: they referenced release artefacts that are no longer published and configuration URLs that have moved.
.codeclimate.yml and sonar-project.properties are no longer used by CI.

This PR has been tested by:

Unit Tests — N/A (documentation and configuration-file removal only; no code paths touched)
Manual Testing — verified every claim in AGENTS.md against the build configuration and sources, including running each command in the pre-commit checklist; confirmed all moved paths and cross-document links resolve

Follow up

None.

Extra details

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)

# Conflicts: # start.sh # start.sh.simple

0xbigapple · 2026-09-17T09:27:16Z

+
+## Commit Convention
+
+`type(scope): description` (Conventional Commits), 10–72 chars, no trailing period.


[SHOULD] Suggest keeping this section consistent with the content and requirements in CONTRIBUTING.md (for example, the lower-case description rule and the full scope list).

Agreed. Rather than restating the rules and risking drift, I've cut the section down to a pointer at CONTRIBUTING.md#commit-messages, keeping only the note that .github/workflows/pr-check.yml is what validates PR titles and descriptions. CONTRIBUTING.md stays the single source.

0xbigapple · 2026-09-17T09:32:18Z

-The java-tron project comes with several runnable artifacts and helper scripts found in the project root and build directories.
+The java-tron project comes with several runnable artifacts found in the build directories.

 |     Artifact/Script     | Description |


0xbigapple · 2026-09-17T09:57:21Z

+
+**Actuator:**
+- New actuators are registered automatically: place the class in the `org.tron.core.actuator` package, extend `AbstractActuator`, and pass the `ContractType` to `super(...)` from a no-arg constructor. `TransactionRegister.registerActuator()` discovers it by reflection at startup — there is no manual registration step.
+- Charge fees before `execute()`.


[DISCUSS] Could you clarify what "before execute()" refers to here? As far as I can see, an actuator's own fee is charged inside execute().

0xbigapple · 2026-09-17T10:22:11Z

+```
+
+- Main entry point: `org.tron.program.FullNode`.
+- Tests run in parallel locally, serially in CI (detected via the `CI` env var); the test-retry plugin retries up to 5 times.


[SHOULD] Tests also run in parallel in CI: framework/build.gradle sets maxParallelForks without checking the CI env var

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

Little-Peony added 2 commits September 14, 2026 15:27

merge

3e90afb

chore: remove obsolete start scripts

6266117

# Conflicts: # start.sh # start.sh.simple

SeriousCoding789 mentioned this pull request Sep 14, 2026

Tracking: code refactor and cleanup #6921

Open

Little-Peony force-pushed the fix_readme branch from 0ca52e5 to 6266117 Compare September 14, 2026 07:29

SeriousCoding789 changed the base branch from develop to release_v4.8.3 September 15, 2026 03:04

update agents.md

a6dcbc6

SeriousCoding789 requested review from 0xbigapple and 317787106 September 17, 2026 06:44

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

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

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

Navigation Menu

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

docs: add AGENTS.md and reorganize project documentation#6871
SeriousCoding789 wants to merge 20 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 Sep 17, 2026

Uh oh!

SeriousCoding789 Sep 17, 2026

Uh oh!

0xbigapple Sep 17, 2026

Uh oh!

0xbigapple Sep 17, 2026

Uh oh!

0xbigapple Sep 17, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

8 participants


		## Commit Convention

		`type(scope): description` (Conventional Commits), 10–72 chars, no trailing period.

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 Sep 17, 2026

Choose a reason for hiding this comment

Uh oh!

SeriousCoding789 Sep 17, 2026

Choose a reason for hiding this comment

Uh oh!

0xbigapple Sep 17, 2026

Choose a reason for hiding this comment

Uh oh!

0xbigapple Sep 17, 2026

Choose a reason for hiding this comment

Uh oh!

0xbigapple Sep 17, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

8 participants

SeriousCoding789 commented Jul 13, 2026 •

edited

Loading