Repository documents
Every repository in the family carries the same documents in the same places: a README that is a landing page, a
changelog, the license and its notice, the files that coding agents and contributors read, a docs/ folder, the bug
report form and the source of the icon. Whoever has found their way around one app’s repository finds it in any
other. This page says which files there are and what each holds; what the documentation as a whole must cover, and
for which reader, is Documentation.
Start from the template. adl-desktop-app-template carries an example of every file on this page,
filled in for a placeholder app, ExampleApp. scripts/rename.sh <AppName> <package> renames it to yours.
Rules on this page 11
| ID | Level | Rule |
|---|---|---|
| REPO-01 | MUST | README.md is a landing page with these parts: logo, badges, a one-paragraph pitch, the
hero screenshot, highlights, install, build, command line, config folder, license. Detail lives on the website,
which the README links, so the README stays short: at most 250 lines.
|
| REPO-02 | MUST | CHANGELOG.md follows Keep a Changelog 1.1 and
SemVer: an ## [Unreleased] section with Added / Changed / Fixed / Removed, and each entry opens with a bold
one-line summary written for users.
|
| REPO-03 | MUST | LICENSE is MIT, “Copyright (c) 2026 Adrián Arturo De León Saldivar”, with the year the app
started in: 2026 for the six apps, later for a newer one.
|
| REPO-04 | MUST | NOTICE gives the app name, the copyright, “licensed under the MIT License”, then every
bundled third-party component with its license (Inter is OFL, AtlantaFX is MIT, OpenJFX is GPLv2+CPE…). The
installers carry NOTICE too.
|
| REPO-05 | MUST | AGENTS.md holds the operational rules for coding agents: essential commands,
worktree-per-task, the change checklist. It is not a changelog. A short CLAUDE.md points to it.
|
| REPO-06 | MUST | CONTRIBUTING.md says how to build, test, format, and open a PR.
|
| REPO-07 | MUST | docs/ holds architecture.md, conventions.md, testing.md, gotchas.md, release.md,
building-and-packaging.md and decisions/ (ADRs). The folder’s index, docs/README.md, is
DOCS-12.
|
| REPO-08 | MAY | TODO.md holds the open list, kept in the same PR as the change.
|
| REPO-09 | MUST | .github/ISSUE_TEMPLATE/bug_report.yml is an issue form, and the in-app Report a Problem
fills it: the link it opens names the form and carries the environment and the report as query parameters named
by the ids of the form’s two fields for them (Editora’s ids are environment and report).
|
| REPO-10 | MUST | branding/ holds the source SVG of the icon. The PNG, ICNS and ICO generated from it sit
beside it or in packaging/.
|
| REPO-11 | SHOULD | Every script in scripts/ is a Java source file the JDK runs as it is (java scripts/Name.java, a compact source file or an ordinary class) or an sh or bash script.
|
- REPO-01 MUST
README.mdis a landing page with these parts: logo, badges, a one-paragraph pitch, the hero screenshot, highlights, install, build, command line, config folder, license. Detail lives on the website, which the README links, so the README stays short: at most 250 lines.- Check (code):
README.mdhas each of those parts, links to the website for the rest, and runs to at most 250 lines (wc -l README.md). - Reference: Editora
README.md(221 lines) and the template’sREADME.md(155); Termina’s has 152 and Mirada’s 172. Three are over the 250: Torrenta’s runs to 433 lines, Modula’s to 364 and nux’s to 313.
- Check (code):
- REPO-02 MUST
CHANGELOG.mdfollows Keep a Changelog 1.1 and SemVer: an## [Unreleased]section with Added / Changed / Fixed / Removed, and each entry opens with a bold one-line summary written for users.- Check (code): the file’s first section is
## [Unreleased]and the others are headed by a SemVer number and a date (## [x.y.z] - YYYY-MM-DD); the entries of a section sit under### Added,### Changed,### Fixedor### Removed, whichever it has entries for (Keep a Changelog’s other two,### Deprecatedand### Security, are as good); and every entry starts with- **. - Reference: Termina
CHANGELOG.mdand Mirada’s, where every entry opens in bold. In Editora’sCHANGELOG.md1,804 of 2,173 entries do: the older ones don’t, and some sections have headings of its own (### Performance,### Internal,### Packaging), as some of Modula’s and nux’s do. Torrenta’s sections are headed## Unreleasedand## 0.4.1 — 2026-10-28, without the brackets.
- Check (code): the file’s first section is
- REPO-03 MUST
LICENSEis MIT, “Copyright (c) 2026 Adrián Arturo De León Saldivar”, with the year the app started in: 2026 for the six apps, later for a newer one.- Check (code):
LICENSEopens withMIT Licenseand has that copyright line, with a year from 2026 on. - Command:
[ -f pom.xml ] || { echo 'not an app root: no pom.xml here'; exit 1; }; tr -d '\r' < LICENSE | head -n 1 | grep -qx 'MIT License' && tr -d '\r' < LICENSE | grep -qxE 'Copyright \(c\) 20(2[6-9]|[3-9][0-9]) Adrián Arturo De León Saldivar' || { head -n 3 LICENSE; false; } - Reference: Editora
LICENSE.
- Check (code):
- REPO-04 MUST
NOTICEgives the app name, the copyright, “licensed under the MIT License”, then every bundled third-party component with its license (Inter is OFL, AtlantaFX is MIT, OpenJFX is GPLv2+CPE…). The installers carryNOTICEtoo.- Check (code):
NOTICEopens with the app’s name, the copyright and the MIT sentence, and names every runtime dependency inpom.xmland every bundled font with its license; and the build putsNOTICEinto what every installer carries (a<resource>that packages it into the application jar in Editora; an argument tojpackageor a packaging script does it as well). A test that asserts it is the surest evidence. - Reference: Editora
NOTICEandpom.xml(the<resource>that packagesLICENSEandNOTICEinto the application jar); two tests hold it:NoticeCoverageTestfails when a runtime dependency inpom.xmlhas noNOTICEentry, andBuildHygieneTestwhen the pom no longer packages the two files.
- Check (code):
- REPO-05 MUST
AGENTS.mdholds the operational rules for coding agents: essential commands, worktree-per-task, the change checklist. It is not a changelog. A shortCLAUDE.mdpoints to it. - REPO-06 MUST
CONTRIBUTING.mdsays how to build, test, format, and open a PR.- Check (code):
CONTRIBUTING.mdnames the build, test and format commands and the PR step. - Reference: Editora
CONTRIBUTING.md.
- Check (code):
- REPO-07 MUST
docs/holdsarchitecture.md,conventions.md,testing.md,gotchas.md,release.md,building-and-packaging.mdanddecisions/(ADRs). The folder’s index,docs/README.md, is DOCS-12.- Check (code): each of those paths exists under
docs/. - Reference: Editora
docs/.
- Check (code): each of those paths exists under
- REPO-08 MAY
TODO.mdholds the open list, kept in the same PR as the change.- Check (code):
TODO.mdexists at the root. - Reference: Editora
TODO.md.
- Check (code):
- REPO-09 MUST
.github/ISSUE_TEMPLATE/bug_report.ymlis an issue form, and the in-app Report a Problem fills it: the link it opens names the form and carries the environment and the report as query parameters named by the ids of the form’s two fields for them (Editora’s ids areenvironmentandreport).- Check (code): the form is at that path and has a field for the environment and a field for the report, each
with an
id; and the link Report a Problem builds names the form’s file and carries one query parameter per field, named by the field’s id (template=bug_report.yml&environment=…&report=…in Editora). The ids are the app’s to choose, as long as the form and the link agree. - Reference: Editora
.github/ISSUE_TEMPLATE/bug_report.ymlandreport/ProblemReport.java, which builds the link. The template, Termina, Torrenta and Mirada have the same form, ids and link; Modula and nux have no issue form.
- Check (code): the form is at that path and has a field for the environment and a field for the report, each
with an
- REPO-10 MUST
branding/holds the source SVG of the icon. The PNG, ICNS and ICO generated from it sit beside it or inpackaging/.- Check (code):
branding/has an.svg; thejpackageicon paths inpom.xmlpoint at the generated files. - Reference: Editora
branding/editora-icon.svg, witheditora.png,.icnsand.icobeside it; the template keeps them inpackaging/icons/.
- Check (code):
- REPO-11 SHOULD Every script in
scripts/is a Java source file the JDK runs as it is (java scripts/Name.java, a compact source file or an ordinary class) or anshor bash script.- Why: every app already needs the JDK, and a Java script runs the same on Windows, macOS and Linux. A Python or Node script makes every contributor and CI runner install a second toolchain for one step. A script that runs on Windows is easier to keep in Java than in bash.
- Check (code): no file under
scripts/is Python, JavaScript, TypeScript, Ruby, Perl, Groovy, Lua, PHP, PowerShell or a batch file, and every shebang there namessh,bashorjava. Data files beside the scripts (fixtures, lists, templates) are not scripts. - Command:
[ -f pom.xml ] || { echo 'not an app root: no pom.xml here'; exit 1; }; [ -d scripts ] || exit 0; bad=$(find scripts -type f | while IFS= read -r f; do if printf '%s\n' "$f" | grep -qE '\.(py|js|mjs|cjs|ts|rb|pl|ps1|bat|cmd|groovy|kts|lua|php)$'; then echo "$f"; continue; fi; l=$(head -n 1 "$f" | tr -d '\r'); if printf '%s\n' "$l" | grep -q '^#!'; then printf '%s\n' "$l" | grep -qE '^#! *(/usr)?/bin/(env +(-S +)?)?((ba|da)?sh|java)( |$)' || echo "$f: $l"; fi; done); [ -z "$bad" ] || { printf '%s\n' "$bad"; false; } - Reference: Editora
scripts/, whose Java scripts have their own tests, run byscripts/lib/RunTests.java(docs/testing.md).

README badges (in this order)
Section titled “README badges (in this order)”The template’s README carries this row, and an app made from it starts with it:
[](…/actions/workflows/ci.yml)[](…/releases/latest)[](LICENSE)[](<homepage>/docs/pauta/)[](…/stargazers)
What is required of the row is in two rules: REPO-01 asks for badges, and
PAUTA-15 for the Pauta badge among them. The other seven and their order are the
template’s: a convention, not a rule. Editora’s README has those seven in this order, with Java-25 and
JavaFX-27 where the template writes 25%2B and 27%2B, and no Pauta badge yet.
The Pauta badge names the edition and the conformance, in green 2ea043 for Complete, blue 5b8def for Core and
amber d29922 for Partial, and links to the app’s Pauta conformance docs page; a test holds
it to pauta.version and the computed conformance (Conformance). The template’s badge
reads Pauta 6.0.0 · Complete, in green, and the README line beside it says “Built to”; at Partial that line says
“Working toward” instead.
The rest of this section describes Editora’s README and is not a rule. Its hero screenshot is a <picture> with a
dark srcset under prefers-color-scheme: dark, so GitHub shows the screenshot that matches the reader’s theme,
and it states that the app is built with the help of AI coding tools.
Pauta 6.0.1 · · Changelog · This page in the latest edition