docs: migrate README.md / README.zh-CN.md to a single NRG template - #239
Open
andriishin wants to merge 1 commit into
Open
docs: migrate README.md / README.zh-CN.md to a single NRG template#239andriishin wants to merge 1 commit into
andriishin wants to merge 1 commit into
Conversation
andriishin
force-pushed
the
nrg-migration
branch
from
April 28, 2026 06:41
e035870 to
cf38e17
Compare
Replace the two hand-maintained README files with a single README.src.md, regenerated in CI by nanolaba/nrg-action@v1 on each push to master. The two outputs are byte-for-byte identical to the originals (modulo a 2-line auto-generated header NRG injects at the top of every output). A drift-check job runs on PRs that touch README.src.md or either generated README, failing the build with a unified diff if a contributor edited one of the generated files instead of regenerating it from the template. <check>false</check>-equivalent for push events keeps the build forgiving until the workflow settles in.
andriishin
force-pushed
the
nrg-migration
branch
from
April 28, 2026 07:39
cf38e17 to
41283bf
Compare
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.zh-CN.mdare hand-maintained side-by-side. Both files are ~1880 lines and follow the same structure section-by-section, so each new package or feature added to the project means editing the same paragraph in two places. Drift between the two is easy to introduce and hard to spot in review.This PR migrates both files to a single source-of-truth template using Nanolaba Readme Generator (NRG) — a small Java 8 tool that turns one
README.src.mdinto N localized README files. Combined with the bundled GitHub Actionnanolaba/nrg-action@v1, regeneration happens in CI on every push tomaster— no Java toolchain needed locally, no Go-side dependency added, just YAML.What changes
README.src.md— the unified source (~3760 lines). Each line is tagged<!--en-->or<!--zh-CN-->so it appears only in that language's output. NRG strips the markers from the final files. The template was generated programmatically from the existing two files: each line ofREADME.<lang>.mdgot its language marker appended verbatim, and the two streams were concatenated. Regenerated outputs are byte-identical to today's files (modulo a 2-line auto-generated header)..github/workflows/nrg.yml— runsnanolaba/nrg-action@v1(pinned to NRG1.1):masterthat touchesREADME.src.mdor the workflow file: regenerates and auto-commits any changed READMEs.README.md,README.zh-CN.md,README.src.md): runs incheckmode — fails with a unified diff if a contributor edited a generated file instead of regenerating from the template.README.md(+2 lines),README.zh-CN.md(+2 lines) — regenerated. The only change is the 2-line auto-generated header at the top. Body content is byte-for-byte identical.The non-default Chinese filename
README.zh-CN.mdis produced by declaring the language aszh-CN(rather thanzh) — NRG's default output pattern<base>.<lang>.mdthen yieldsREADME.zh-CN.mddirectly, no override needed.Verification
Locally, regenerating with NRG
1.1from Maven Central against currentmaster(commit 3d1cd97) produces output that diffs against the originals only by the 2-line auto-generated header on each file. Zero functional content change. Tested with the samenanolaba/nrg-action@v1setup that the workflow uses (Java 17 + NRG 1.1 from Maven Central).What's intentionally NOT in this PR
README.src.md. Future PRs can extract shared structural elements (badge URLs, table headers, code blocks) into shared regions — incremental, reviewable changes rather than one big rewrite.go.mod, or any build step. Only the README files and a docs workflow.How to regenerate locally
(Once the workflow is merged,
git pushto a branch and CI will do this for you.)About NRG
com.nanolaba:readme-generator— open-source, Apache 2.0, Java 8+. Ships as a CLI, Maven plugin, GitHub Action, and library. The action approach used here requires zero local toolchain setup — the Java is provisioned by the action itself.