docs: make the design document English and keep a Korean translation - #7
Merged
Merged
Conversation
DESIGN.md is now the English norm, with the Korean text kept alongside it as DESIGN.ko.md. Step headings carry explicit numbers so code comments can anchor to them, and the two files share section order for diffing. Go comments, CLAUDE.md and the AGENTS.md banner move to English as well. A CI job rejects a pull request that changes one design file without the other, so the translation cannot go stale unnoticed.
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.
Everything a reader arriving from upstream sees is now in English, and the Korean design text
is kept as a translation rather than lost.
Structure
DESIGN.md— English, and the normative design document. Step headings carry explicitnumbers (
Step 1.…Step 5.) so code comments can anchor to them.DESIGN.ko.md— the Korean translation. Same section order and numbering, so the two filesdiff against each other.
Only one of them is a norm. Two documents both claiming to be the source of truth drift, and
the moment they drift the "if the code disagrees with DESIGN.md, the code is wrong" rule stops
meaning anything.
Also in this change
DESIGN.md 3단계became
DESIGN.md step 3.CLAUDE.mdis in English and gains the rule that a design change touches both files.AGENTS.mdbanner is in English.README.mdlinks the translation instead of promising one.Design syncworkflow fails a pull request that moves one design file without the other.It needs its own workflow file because the main CI ignores
**.md.One content fix
DESIGN.md§1 pointed at step 4 for where the loop stalls on a workload toleratingunschedulable. That check moved to step 3 in an earlier change and the cross-reference didnot follow. Both files now say step 3. Nothing else about the design changed — this is a
language change, not a design change.
Verification
gofmt -lclean,make lintreports 0 issues,make test(unit + envtest) passes. e2e wasnot run; only comments changed in the test sources.