[DONE] 변경 기록을 릴리스마다 한 장으로 나눠 docs/releases/ 에 두고 루트엔 최근 셋만 남긴다

[patternflow-bot]

dev / https://claude.ai/code/session_013qn5ntPp12SuNmMVVyGTbh

947줄짜리 CHANGELOG.md 를 정리 1단계 계획서 B1 대로 릴리스마다 한 장씩 docs/releases/ 로 나눴다. 30장 모두 글은 그대로 옮겼고 상대 링크 여섯 개만 새 깊이로 고쳤다. 루트엔 최근 세 릴리스와 옛 릴리스 목록만 남아 167줄이 된다. 머지하면 release.py cut 이 새 릴리스 파일을 쓰고, 넷째로 밀려난 절을 루트에서 목록 한 줄로 내린다.

좋아지는 것: 없음

할 일

• D1: docs/releases/v3.0.0.md·v3.1.0.md → v3.0.0-notes.md·v3.1.0-notes.md (git mv, 글 그대로)
• 30절 → docs/releases/vX.Y.Z.md 30장 (머리줄·본문 그대로, 상대 링크 6개만 ../../)
• 루트 CHANGELOG.md(D2): 머리 문장 하나 고침 · [Unreleased] 그대로 · [3.11.0]·[3.10.5]·[3.10.4] 전부 · ## Older releases 아래 27줄
• release.py: cut 이 새 파일을 쓰고 넷째 절을 목록 한 줄로 · 쓴 파일을 커밋 경로에 · docstring
• docs/RELEASING.md: Two commands 문단 · 체크리스트 3단계 · Current release line
• roadmap-data.ts: 「CHANGELOG (2.0.0)」 링크의 href 만
• 검사: 재조립 diff · 루트 세 절 == 파일 · release.py dry run · py_compile · check_links.py · doc-map(CSV 버림) · web check:ci(check:panels 포함)·typecheck·lint · check_versions.py
• head 8818575 의 GitHub CI 초록: docs-links.yml, firmware-checks.yml, firmware-build.yml 다섯 composition, web-ci.yml
• [DONE] 직전 기준 브랜치(dev) 다시 fetch: 9e53a6c 그대로(뒤처진 커밋 0)라 merge 할 것 없음

한 일

• 나눔. git show origin/dev:CHANGELOG.md 의 ## [ 절 30개를 각각 docs/releases/v<버전>.md 로 썼다. 파일 이름엔 늘 v 가 붙는다([3.11.0] → v3.11.0.md, [v1.1.0] → v1.1.0.md). 한 절은 머리줄부터 다음 ## 앞까지다. 그래서 2.0.0 과 v1.1.0 뒤에 있던 --- 구분선은 v2.0.0.md·v1.1.0.md 끝에 그대로 따라갔다. 고친 것은 상대 링크 여섯 개뿐이다(BUILD_GUIDE.md, investigations 셋, panel-compatibility.md, pfst-v2-spec.md → 앞에 ../../). 사이트 링크(/roadmap, /update 같은 것)와 https 링크는 그대로다.
• 루트. 머리, [Unreleased](hub 가 줄을 넣는 곳이라 손대지 않음), 최근 세 절 전부, 그다음 ## Older releases 아래 옛 릴리스마다 한 줄(- [3.10.3](docs/releases/v3.10.3.md) - 2026-09-17, 머리줄 꼴 그대로). 새로 쓴 글은 머리의 한 문장뿐이다: …is on [GitHub Releases](…). Every release has its own file in [docs/releases/](docs/releases/); this file keeps the three newest in full and links the rest. (원래 ; this file is the complete record.)
• release.py. 나누기는 손으로 하지 않고 release.py 에 새로 넣은 도우미(SECTION, release_file, as_filed, older_line)로 했다. 그래서 30장은 앞으로 cut 이 쓸 꼴과 같다. cut 은 bump_changelog 다음에 file_changelog 를 돌린다. 새 절을 docs/releases/vX.Y.Z.md 로 쓰고(상대 링크 ../../), 루트에서 넷째가 된 절을 빼서 ## Older releases 맨 위 한 줄로 만든다. 쓴 파일은 release: vX.Y.Z 커밋 경로에 들어간다. 무엇이든 쓰기 전에 check_filing 이 두 가지를 본다: 새 버전 파일이 이미 있으면 멈춘다. 루트를 떠날 절이 제 파일과 다르면(루트만 고친 경우) 루트 쪽 글이 사라지니 멈춘다. publish 는 그대로 루트의 최신 절을 읽는다.
• RELEASING.md. Two commands 문단에 「dates the changelog section and files it in docs/releases/」. 체크리스트 3단계는 손으로 할 때 같은 일(파일로 복사, 링크 ../../, 넷째 절을 Older releases 한 줄로). Current release line 첫 문장은 파일이 어디 있고 루트가 무엇을 갖는지로 바꿨다.
• roadmap-data.ts. fw-v2 노드 링크 href 만 ${REPO}/blob/main/docs/releases/v2.0.0.md. 라벨·detail·detailKo 는 그대로.

증거

# 재조립: 루트 머리+[Unreleased] + docs/releases/ 30장(루트가 부르는 차례대로), 링크 고침 되돌려서, dev 와 diff
$ git show origin/dev:CHANGELOG.md | grep -c '](\.\./\.\./'
0
$ python3 reassemble.py . > rebuilt.md && git show origin/dev:CHANGELOG.md | diff - rebuilt.md && echo identical
identical (947 lines)

# 루트에 남은 세 절 == 제 파일
3.11.0 root section == file: True
3.10.5 root section == file: True
3.10.4 root section == file: True

# D1 두 장이 그대로 옮겨졌다
$ git diff -B -M --stat origin/dev   # (30장 줄은 뺐다)
 CHANGELOG.md                                 | 1114 ++++----------------------
 docs/RELEASING.md                            |    7 +-
 docs/releases/{v3.0.0.md => v3.0.0-notes.md} |    0
 docs/releases/{v3.1.0.md => v3.1.0-notes.md} |    0
 firmware/toolchain/release.py                |   71 +-
 web/src/app/roadmap/roadmap-data.ts          |    2 +-
 36 files changed, 1133 insertions(+), 1051 deletions(-)
$ diff <(git show origin/dev:docs/releases/v3.0.0.md) docs/releases/v3.0.0-notes.md   → 차이 없음 (v3.1.0 도)

# release.py dry run, 버리는 worktree 에서 (git worktree add --detach … HEAD)
$ python3 firmware/toolchain/release.py cut v3.11.1 --no-build --no-commit --no-web-checks --any-branch
== cut v3.11.1
  net_config.h: PF_IMPROV_FW_VERSION -> 3.11.1
  CHANGELOG.md: [Unreleased] -> ## [3.11.1] - 2026-10-14
  CHANGELOG.md: [3.10.4] -> a line under 'Older releases'
  docs/releases/v3.11.1.md: written
  AGENTS.md: current v3.11.1
  ...
$ grep -n '^## ' CHANGELOG.md
5:## [Unreleased]
7:## [3.11.1] - 2026-10-14
30:## [3.11.0] - 2026-10-04
101:## [3.10.5] - 2026-10-02
135:## Older releases
$ sed -n '/^## Older releases/,+3p' CHANGELOG.md
## Older releases

- [3.10.4](docs/releases/v3.10.4.md) - 2026-09-19
- [3.10.3](docs/releases/v3.10.3.md) - 2026-09-17
root [3.11.1] == docs/releases/v3.11.1.md
publish reads [3.11.1]: 20 lines, first: ### Hardware
# 이어서 cut v3.11.2 --allow-empty-changelog → [3.10.5] 가 목록 맨 위로
# 루트의 [3.11.0] 에만 한 줄 넣고 cut v3.11.3 →
release: CHANGELOG.md's [3.11.0] section and docs/releases/v3.11.0.md differ; make them agree before cutting, since the section leaves the root
exit 1   (CHANGELOG.md 는 손대지 않음, v3.11.3.md 없음)
# docs/releases/v3.11.5.md 를 미리 만들고 cut v3.11.5 →
release: docs/releases/v3.11.5.md already exists
exit 1
$ git worktree remove --force …   # 치움
$ python3 -m py_compile firmware/toolchain/release.py
py_compile ok

$ python3 .github/scripts/check_links.py
All 662 relative links resolve

$ git fetch --tags && (cd web && npm run doc-map)
1044 links from 204 files → docs/investigations/2026-10-doc-map.csv
0 do not resolve
$ git checkout docs/investigations/2026-10-doc-map.csv   # lane C 가 커밋한다

$ python3 firmware/toolchain/check_versions.py
versions agree: core v3.11.0, audio v0.7.0, performance v0.4.0 - in net_config.h, the overrides, AGENTS.md, the manifest and the /editions cards, images on the shelf; try-out images: clock-v0.1.5, midi-v0.1.0

# web/
$ npm run typecheck      → exit 0, tsc --noEmit prints nothing
$ npm run lint           → exit 0, ✖ 12 problems (0 errors, 12 warnings)   # step 0 기준선과 같은 12개
$ npm run check:ci       → exit 0, 25 suites, last line: All module cache checks passed.
                           (check:panels 포함: Test Files 35 passed (35), Tests 478 passed (478))

• head 8818575 의 GitHub CI: Docs point at files that exist(docs-links.yml) success, Core knows no features(firmware-checks.yml) success, firmware-build.yml 의 default·audio·performance·clock·midi 다섯 개 success, Web CI(web-ci.yml) build success.
• build.sh all 은 이 컨테이너가 PlatformIO 레지스트리에 닿지 못해(기준선과 같음) 위 firmware-build.yml 다섯 composition 이 기록이다. .pfm 캐시 키는 움직일 수 없다: 툴체인 revision 은 abi/*.h·공유 src/·module.ld·build_module.py·port_preset.py 를 해시하고 release.py 는 그중 아무것도 아니다(check:modcache 도 통과).

정리 기록 (RFC §2.11)

• 옮긴 것: CHANGELOG.md 의 30절 → docs/releases/vX.Y.Z.md(루트엔 최근 셋과 목록), docs/releases/v3.0.0.md·v3.1.0.md → -notes.md
• §2.1 명령: web check:ci·check:panels·typecheck·lint 통과. build.sh all 은 CI(firmware-build.yml)
• doc-map 행: CHANGELOG.md 에서 나가던 상대 6행은 출처가 그 절의 파일로(docs/releases/v1.0.0.md → BUILD_GUIDE.md 등), 옛 절에만 있던 site 행 4개(/panel-tuner.html, /roadmap, /update, /variants)도 그 파일로. 새 행: CHANGELOG.md → docs/releases 와 목록의 27장, roadmap-data.ts → docs/releases/v2.0.0.md. D1 두 장의 나가는 행 10개는 출처 이름만 -notes.md. 전부 yes.

300줄 (D3)

새로 쓰거나 고친 줄은 111줄이다: CHANGELOG.md +30 −1(머리 한 줄, ## Older releases, 목록 27줄), release.py +70 −1, RELEASING.md +4 −3, roadmap-data.ts +1 −1. 나머지는 옮긴 글이고, 위 재조립 diff 가 그대로임을 보인다.

for another lane (C3)

• docs/README.md 53행을 이렇게:
  - [`releases/`](releases/) — every release's changelog section as written, one file each (`vX.Y.Z.md`), back to v1.0.0; `CHANGELOG.md` at the root keeps the three newest in full and links the rest. `v3.0.0-notes.md` and `v3.1.0-notes.md` are long-form notes for two July 2026 releases, beside the v3.0.0 launch checklist; notes since 3.2 are on [GitHub Releases](https://github.com/engmung/Patternflow/releases)
• docs/REPOSITORY.md 의 docs/ 줄: 이름을 넣는 편을 권한다. 루트 changelog 가 이제 독자를 그리로 보낸다. 「project records」 를 「project records (releases/, one file per release)」 로.

실행법

# 재조립 스크립트는 커밋하지 않았다(계획서). 같은 일:
python3 - <<'PY'
import re, subprocess
root = open("CHANGELOG.md").read()
first = re.search(r"^## \[(?!Unreleased\])", root, re.M).start()
head = root[:first].replace(". Every release has its own file in [docs/releases/](docs/releases/); this file keeps the three newest in full and links the rest.", "; this file is the complete record.")
names = [f"v{l.lstrip('v')}.md" for l in re.findall(r"^## \[(?!Unreleased\])([^\]]+)\]", root, re.M)]
names += re.findall(r"^- \[[^\]]+\]\(docs/releases/(v[^)]+\.md)\)", root, re.M)
rebuilt = head + "\n".join(open(f"docs/releases/{n}").read().replace("](../../", "](") for n in names)
print("identical" if rebuilt == subprocess.run(["git","show","origin/dev:CHANGELOG.md"],capture_output=True,text=True).stdout else "DIFFERS")
PY
python3 .github/scripts/check_links.py
git fetch --tags && (cd web && npm ci && npm run doc-map) && git checkout docs/investigations/2026-10-doc-map.csv
cd web && npm run check:ci && npm run typecheck && npm run lint

가정

• 메인테이너 답 6은 docs/voice.md 가 머지되기 전에는 글을 쓰는 1단계 PR 을 열지 않는다고 한다. voice.md 는 아직 없다. 총괄이 B1 을 지금 맡겼고 계획서도 B1 을 「now」로 둔다. 그래서 하되 새 글을 계획서가 말한 만큼만 썼다: 머리 한 문장, RELEASING.md 세 곳(무엇이 어디 쓰이는지만), 코드 주석. 셋 다 §2.10 을 따랐다(줄표로 절을 잇지 않음, 금지어 없음). voice.md 가 먼저 머지돼야 한다면 이 PR 은 그때까지 기다리면 되고, 고칠 곳은 그 몇 줄이다.
• D1(질문 7, 아직 답 없음)을 따랐다. §2.9 는 나눈 뒤의 docs/releases/*.md 를 잠그고 잠긴 파일 옮기기는 메인테이너 승인이 필요하다고 한다. 두 장은 글자 하나 안 바뀐 이름 바꾸기다(위 diff). 두 장의 머리 배너(「CHANGELOG.md at the root is the complete record」)는 D1 대로 그대로 두었다. 그 시점의 기록이다.
• --- 구분선 두 개는 절 끝에 붙은 채 v2.0.0.md·v1.1.0.md 끝에 남겼다. 빼면 「그대로」가 깨지고 재조립에 예외가 생긴다. 보이는 건 파일 끝 가로줄 하나다.
• check_filing 의 「루트 절과 파일이 다르면 멈춤」은 계획서에 없다. D2 는 어긋남 찾기를 2단계 몫으로 둔다. 다만 cut 이 루트에서 글을 지우는 순간이라, 지우는 글이 파일에 그대로 있는지만 본다. 어긋남 전체를 찾는 검사(질문 9)는 여전히 2단계 몫이다.
• as_filed 는 Markdown 인라인 링크 ](…) 만 고친다. 지금 changelog 엔 참조식 링크·<img src> 가 없다(grep 으로 확인).
• roadmap-data.ts 의 링크는 원래 레포(engmung/Patternflow) main 을 가리킨다. 이 PR 이 원래 레포 main 에 들어가야 맞는다. A1 과 같다. 같은 파일의 둘째 링크(fw-foundation 노드의 「CHANGELOG.md」)는 계획서가 짚지 않았고, 루트 목록이 3.9.3 파일로 이어 주니 두었다.
• shelf.sh 의 오류 문구 「Bump the define (and CHANGELOG.md)」 는 여전히 맞고 B1 파일도 아니라 두었다.
• 라벨 cleanup·step-1(D4)은 포크에 없어 붙이지 않았다(A1 과 같음).
• 작업 지시대로 CHANGELOG.md 고치기가 이 PR 의 일이지만 [Unreleased] 는 손대지 않았다(계획서). 이 PR 자체의 changelog 줄은 아래에 있다.

Changelog

Docs

• CHANGELOG.md is split by release into docs/releases/. Every release has its own file, vX.Y.Z.md, back to v1.0.0, with its section copied as written and its relative links two folders up; the root keeps the three newest in full and a line linking each older one. release.py cut writes the new release's file and moves the fourth-newest section out of the root. The long-form notes for 3.0.0 and 3.1.0 are now v3.0.0-notes.md and v3.1.0-notes.md.

🤖 Generated with Claude Code

https://claude.ai/code/session_013qn5ntPp12SuNmMVVyGTbh