From bf6ef3c4dcc520ba7bd68e8902e6d1777dc4df09 Mon Sep 17 00:00:00 2001 From: Ryan Barlow <7389646+ryanbarlow97@users.noreply.github.com> Date: Sat, 3 Oct 2026 22:38:42 +0000 Subject: [PATCH] docs: describe the source README layout The README layout was only defined by example, and several source READMEs had grown configuration references and release notes. Write the layout down next to the rule that keeps source READMEs short. Co-Authored-By: Claude Opus 5.5 (1M context) --- MAINTAINING.md | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/MAINTAINING.md b/MAINTAINING.md index 502aa97..d46c52d 100644 --- a/MAINTAINING.md +++ b/MAINTAINING.md @@ -2,6 +2,17 @@ Put technical manuals in `projects//`, using the canonical PascalCase repository name (for example, `ActivityTF`, `VehicleFramework`, or `ServerAssets`). Keep source repository READMEs short and link to the matching project index here. +Source READMEs use this layout, in order: + +1. `# `, a one-line `>` tagline, and a short introduction for players and staff. +2. `## Features`: bullets in the form `- **Feature** — description.` +3. Optional short narrative sections, such as related projects, credits or project background. +4. `## Documentation`: a link to the project index here, followed by `Technical documentation is maintained in [TF-Minecraft/Docs](https://github.com/TF-Minecraft/Docs).` Links to individual guides may follow. +5. `## Tests` or `## Tests and coverage`, for repositories with test suites: how to run them, the tools used, report locations, any enforced coverage gate, and what the tests do not cover. +6. `## License`, last, containing only the licence statement. + +Configuration keys and examples, command references, upgrade or installation order, troubleshooting, persistence internals and release notes belong in the project guides here, not in source READMEs. When a feature PR changes behaviour, update the guide rather than adding a README section. Keep other technical Markdown files out of source repository roots; `CONTRIBUTING.md` for upstream projects and TLibs `DEPENDENCIES.md` are the exceptions. + When changing behavior, update the relevant guide in a docs PR and link it from the implementation PR. Use relative links for other guides and GitHub source links for code. Commands and filesystem paths refer to the source checkout unless a guide says otherwise. Use [PLATFORM.md](PLATFORM.md) as the shared **Java 21 / Minecraft 1.21.10** baseline. Every project index links to it. Keep runtime versions separate from Maven API dependencies, Java compiler targets and plugin loader metadata; document any deviation from the baseline. When source build settings change, update the matrix and build instructions.