ci(nrg): generate README.md and README.fr.md from a single template#489
Open
andriishin wants to merge 1 commit intocodegouvfr:mainfrom
Open
ci(nrg): generate README.md and README.fr.md from a single template#489andriishin wants to merge 1 commit intocodegouvfr:mainfrom
andriishin wants to merge 1 commit intocodegouvfr:mainfrom
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 main. 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, badge, or HTML structural element changed.
How the template works:
- README.src.md uses per-line <!--en--> / <!--fr--> markers for
translated bits. Untagged lines (HTML wrappers, badge anchors,
img tags, <br>) render in both — about 28% of the template is
shared structural code.
- Default file-name pattern produces README.md (default lang = en);
nrg.fileNamePattern.fr maps the fr output to README.fr.md.
CI behavior:
- regenerate (push to main, 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.
Hardenings: workflow default permissions = contents: read; regenerate
job overrides to contents: write only where needed for git push.
nanolaba/nrg-action pinned to commit SHA for supply-chain hygiene.
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.fr.mdare currently maintained as two hand-edited files (~6.5 KB each, 130 / 127 lines). About 28% of their lines are byte-identical (HTML wrappers, badge anchors, image tags), the rest is the same prose translated into the other language.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 tomain.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
main:No translation content, link, code block, badge, image, or HTML element changed. The 3-line metadata header marks each output as auto-generated:
How the template works
<!--en-->only render inREADME.md.<!--fr-->only render inREADME.fr.md.Adding a third language later (e.g. Spanish) is purely additive — append
esto<!--@nrg.languages=...-->, add<!--@nrg.fileNamePattern.es=README.es.md-->, and add<!--es-->-tagged lines next to existing<!--en-->/<!--fr-->lines. Existing files stay untouched.CI behavior
Two jobs in
.github/workflows/nrg.yml:regenerate(push tomain, 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.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 if the byte-perfect-mirror approach isn't right for your workflow.