Skip to content

docs: add AGENTS.md and improve documentation discoverability#6865

Closed
Sunny6889 wants to merge 5 commits into
tronprotocol:release_v4.8.2from
Little-Peony:release_v4.8.2_doc_ai
Closed

docs: add AGENTS.md and improve documentation discoverability#6865
Sunny6889 wants to merge 5 commits into
tronprotocol:release_v4.8.2from
Little-Peony:release_v4.8.2_doc_ai

Conversation

@Sunny6889

@Sunny6889 Sunny6889 commented Jul 3, 2026

Copy link
Copy Markdown
Contributor

What does this PR do?

Documentation-only change (no code or build changes) that makes the project easier to navigate for new contributors and AI coding assistants:

  • Adds AGENTS.md at the repository root — a concise contributor/AI guide covering build & test commands, the module layout and one-way dependency direction, the hard constraints (cross-JVM determinism, DB Session usage, actuator / protobuf / API / thread rules), coding & security rules, and the commit convention.
  • Adds a Documentation section to README.md linking the guides under docs/ (configuration, modular architecture & deployment, implementing a customized actuator) and the authoritative Protobuf protocol document.
  • Moves the root protocol document Tron protobuf protocol document.mddocs/protobuf-protocol-document.md (pure rename, no content change): removes the spaces from the filename and consolidates it with the other guides under docs/.
  • Marks the two outdated protocol copies under protocol/src/main/protos/ (English / Chinese, last updated 2022) as superseded, pointing readers to the maintained document.
  • Adds a short security note to docs/configuration.md on protecting a Super Representative's block-producing key (prefer the encrypted keystore, restrict file permissions, never commit a real key).

Why are these changes required?

  • No single entry point for building/navigating the codebase, and the docs/ guides were not linked from the README — hard for contributors and AI assistants to discover.
  • The root protocol document's filename contained spaces (breaks relative Markdown links in several editors/renderers and is awkward for tooling), and the stale copies under protocol/src/main/protos/ did not point to the maintained version.
  • The configuration reference gave no guidance on protecting the Super Representative block-producing key.

This PR has been tested by:

  • Unit Tests: N/A — documentation only, no code or build changes.
  • Manual Testing:
    • Verified every relative link resolves to an existing file and the Markdown renders correctly.
    • Confirmed git records the protocol-document change as a pure rename (R100) with no content diff.
    • Verified the rename does not break the developer documentation: searched all references in tronprotocol/documentation-en (the old filename in any form, java-tron blob/tree/raw links, and .md links) — the file is not referenced there, so no links break.

Follow up

  • Consider linking AGENTS.md from the developer documentation site.

Extra details

  • The maintained protocol document moved: Tron protobuf protocol document.md (repo root) → docs/protobuf-protocol-document.md. Rename only; content unchanged.
  • 6 files changed, +118 lines; no source code, build scripts, or config defaults touched.

@Little-Peony Little-Peony force-pushed the release_v4.8.2_doc_ai branch from e1470e0 to 3c55d86 Compare July 3, 2026 08:19
@Little-Peony Little-Peony force-pushed the release_v4.8.2_doc_ai branch from 3c55d86 to f339051 Compare July 3, 2026 08:27
@Sunny6889 Sunny6889 closed this Jul 3, 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.

2 participants