docs: migrate README.md / README.ja.md to a single NRG template#164
Open
andriishin wants to merge 1 commit intoauthlete:masterfrom
Open
docs: migrate README.md / README.ja.md to a single NRG template#164andriishin wants to merge 1 commit intoauthlete:masterfrom
andriishin wants to merge 1 commit intoauthlete:masterfrom
Conversation
e3261cd to
bfc0241
Compare
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.
bfc0241 to
b93de53
Compare
This was referenced Apr 28, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Why
README.mdandREADME.ja.mdare hand-maintained side-by-side today and have drifted in a handful of places:####in EN but###in JA.[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.mdinto 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
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=…-->).pom.xml— addscom.nanolaba:nrg-maven-plugin:1.1to<build><plugins>(immediately aftermaven-compiler-plugin) somvn compileregenerates both READMEs.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.1from Maven Central against currentmaster(commit 6d5409e, 4.44-SNAPSHOT) produces files that diff against the originals only by: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.1from Maven Central.What's intentionally NOT in this PR
####/###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 inREADME.src.mdonce the template is in place.<check>false</check>is set so the build does not fail on README drift today. A follow-up can set it totrueonce the workflow is comfortable with regenerating before commit.How to regenerate locally
After this PR is merged:
(or
mvn nrg:create-filesfor just the README step, skipping the rest of the build).To preview without touching the plugin first:
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 inpom.xml, no runtime dependency on the plugin once READMEs are committed.