ci(nrg): generate README.md and README.zh_CN.md from a single template#118
Open
andriishin wants to merge 1 commit into
Open
ci(nrg): generate README.md and README.zh_CN.md from a single template#118andriishin wants to merge 1 commit into
andriishin wants to merge 1 commit into
Conversation
Adds README.src.md as the single source for the existing two READMEs and
wires up nanolaba/nrg-action@v1 to regenerate them on push to master. A
drift-check job on PRs catches any direct hand-edits to a generated
file with a clear diff pointing back at README.src.md.
Output preserves both files byte-for-byte except for a 3-line auto-
generated header injected at the top of each. No translation content,
link, code block, image, or heading changed.
How the template works:
- README.src.md uses per-line <!--en--> / <!--zh--> markers for
translated bits (most lines: TOC entries, headings, prose,
descriptive comments). Untagged lines render in both languages —
used for code-block contents, identical structural separators,
and a few shared lines.
- Default NRG file-name pattern produces README.md (default lang =
en); nrg.fileNamePattern.zh maps the zh output to README.zh_CN.md.
CI behavior:
- regenerate (push to master, README.src.md or workflow changes)
regenerates both READMEs and commits as github-actions[bot].
- drift-check (pull_request) fails the PR if a contributor hand-
edits a generated README. Failure log shows a unified diff
pointing back at README.src.md.
Hardenings:
- Workflow default permissions = contents: read; regenerate job
overrides to contents: write only where it needs git push.
- nanolaba/nrg-action pinned to commit SHA (supply-chain hygiene).
- Commit step uses git pathspec exclude pattern so README.src.md
can never be re-staged accidentally.
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
1 participant
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.
What this changes
README.mdandREADME.zh_CN.mdare currently maintained as two separate hand-edited files (~30 KB / 32 KB, 739 / 755 lines). Every commit that touches one needs a parallel edit to the other — with two big files and a non-trivial section structure (TOC + 9 top-level sections + nested sub-sections), that's brittle.This PR consolidates them into a single source —
README.src.md— and adds a GitHub Action (nanolaba/nrg-action@v1) that regenerates both on push tomaster.After the merge: both rendered files on GitHub are unchanged; future content edits land in
README.src.mdonce, and the bot updates both files in a single follow-up commit.Byte-perfect preservation
Locally regenerated with NRG 1.2 — diff vs current
master:No translation content, link, code block, image, anchor, or heading changed. The 3-line metadata header marks each output as auto-generated:
It signals to future contributors not to hand-edit, and the drift-check job below enforces it on PRs.
How the template works
<!--en-->only render inREADME.md.<!--zh-->only render inREADME.zh_CN.md.Most of the template is per-language (TOC entries with locale-specific anchors, prose, headings) — that's just the nature of two large translated docs. The shared parts are mostly the Java code blocks and
mvnsnippets.Adding a third language later is purely additive — append
jato<!--@nrg.languages=...-->, add<!--@nrg.fileNamePattern.ja=README.ja.md-->, and add<!--ja-->-tagged lines next to existing<!--en-->lines. Existing files stay untouched.CI behavior
Two jobs in
.github/workflows/nrg.yml:regenerate(push tomaster, whenREADME.src.mdor the workflow itself changes) — regenerates both READMEs and commits them asgithub-actions[bot].drift-check(pull_request, when any tracked README or the template changes) — fails the PR if a contributor hand-edited a generated file, with a unified diff pointing back atREADME.src.md.Both jobs pinned to
nrg-version: '1.2'. The action itself is pinned to a commit SHA (not the floating@v1tag) for supply-chain hygiene. Permissions scoped per-job:regenerategetscontents: writeforgit push,drift-checkstays read-only.This
pom.xmlJava project is also eligible for thenrg-maven-plugin— drop a 10-line plugin block intopom.xmlandmvn packageregenerates the READMEs locally, no separate workflow needed. Happy to add that as a follow-up if you'd prefer it over the GitHub Action route.If you don't want this
Easy to revert — drop
README.src.md, drop.github/workflows/nrg.yml, restore the two README files. Happy to discuss alternative shapes (e.g. EN-only template + community-managed translations) if the byte-perfect-mirror approach isn't right for your workflow.