Skip to content

docs: migrate README.md / README.ja.md to a single NRG template#164

Open
andriishin wants to merge 1 commit intoauthlete:masterfrom
andriishin:nrg-migration
Open

docs: migrate README.md / README.ja.md to a single NRG template#164
andriishin wants to merge 1 commit intoauthlete:masterfrom
andriishin:nrg-migration

Conversation

@andriishin
Copy link
Copy Markdown

Why

README.md and README.ja.md are hand-maintained side-by-side today and have drifted in a handful of places:

  • The EN file documents two long sections — Code Quality Tools and Contributing Guidelines — that are not in the JA file.
  • The "AuthleteApi Settings" sub-heading is #### in EN but ### in JA.
  • The reference links [5] and [10] legitimately differ between files (JA points to /ja/developers/overview/ and to a Qiita article instead of the Medium one).

This PR migrates both files to a single source-of-truth template using Nanolaba Readme Generator (NRG) — a small Java 8 Maven plugin that turns one README.src.md into N localized README files on every build. The two existing files become regenerated artifacts: editing them by hand is no longer necessary and a comment header at the top warns about it.

What changes

  • New: README.src.md — the unified source. Lines specific to one language are tagged with <!--en--> / <!--ja-->; per-language section titles use inline ${en:'…', ja:'…'}. The two diverging reference links are kept distinct via NRG property overrides (<!--@ref5.ja=…--><!--@ref10.ja=…-->).
  • Modified: pom.xml — adds com.nanolaba:nrg-maven-plugin:1.1 to <build><plugins> (immediately after maven-compiler-plugin) so mvn compile regenerates both READMEs.
  • Modified: README.md (+4 lines), README.ja.md (+27/-10 lines, all cosmetic) — regenerated. EN gets only a 2-line auto-generated header at the top. JA gets the same header plus a few cosmetic differences in setext underline length (------- vs --------) and a couple of extra blank lines around section breaks — both render identically on GitHub.

Verification

Locally, regenerating with NRG 1.1 from Maven Central against current master (commit 6d5409e, 4.44-SNAPSHOT) produces files that diff against the originals only by:

  1. A 2-line header noting the file is auto-generated (top of each output).
  2. In README.ja.md: setext heading underlines are normalised to a single shared length per heading level; this is purely cosmetic — markdown renderers treat any number of dashes as a valid H2 underline.

Total functional content change: zero. Tested with Java 8 and nrg-maven-plugin:1.1 from Maven Central.

What's intentionally NOT in this PR

  • Translation alignment. The drift between languages (Code Quality Tools / Contributing Guidelines sections present only in EN, the ####/### heading-level mismatch) is preserved as-is. This PR is strictly mechanical so review is just "diff says the right things". Surfacing those sections to JA readers is a one-line addition per missing piece in README.src.md once the template is in place.
  • CI hardening. <check>false</check> is set so the build does not fail on README drift today. A follow-up can set it to true once the workflow is comfortable with regenerating before commit.

How to regenerate locally

After this PR is merged:

mvn compile

(or mvn nrg:create-files for just the README step, skipping the rest of the build).

To preview without touching the plugin first:

curl -L -o nrg.jar https://repo1.maven.org/maven2/com/nanolaba/readme-generator/1.1/readme-generator-1.1.jar
java -jar nrg.jar -f README.src.md

About NRG

com.nanolaba:readme-generator — open-source, Apache 2.0, Java 8+. Ships as a CLI, Maven plugin, GitHub Action, and library. ~17 lines of XML in pom.xml, no runtime dependency on the plugin once READMEs are committed.

Replace the two hand-maintained README files with a single
README.src.md, regenerated by nrg-maven-plugin during the compile
phase. Existing per-language content is recreated bit-for-bit
(modulo cosmetic setext underline length and the auto-generated
header NRG injects at the top of every output). The reference
links that legitimately differ between the two files (anchor [5]
ja-localised /developers/overview/ path, anchor [10] linking to a
different write-up) are kept distinct via per-language property
overrides.

The 4.x EN-only sections (Code Quality Tools, Contributing
Guidelines) remain EN-only as before; surfacing them to JA readers
can happen as a focused follow-up once the template is in place.
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.

1 participant