release-copy

name	release-copy
description	LinKHU 버전을 올린 뒤 사용자에게 알릴 문구를 쓸 때 사용. 릴리스 노트에서 사용자 노출 변경만 골라 스토어 설명(docs/store-listing.md)의 업데이트 섹션을 교체하고, 계속 알릴 기능이면 커뮤니티 홍보 글(docs/community-post.md)의 기능 목록에 녹인다. "버전 올렸으니 스토어 문구 써줘", "업데이트 안내 글 써줘", "에브리타임에 올릴 글", "2.6.0 문구로 바꿔줘" 같은 요청에 사용.

릴리스 문구 쓰기

릴리스 노트를 사용자 언어로 다시 쓰는 일이다. 옮겨 붙이는 일이 아니다.

원본 두 개를 제자리에서 갱신한다. 매번 새로 짓지 않는다.

문서	쓰는 곳	독자	릴리스마다 하는 일
docs/store-listing.md	Chrome / Firefox / Whale 설명란, What's new	설치를 고민하는 사람	[vX.Y.Z 업데이트] 섹션을 교체한다
docs/community-post.md	에브리타임 등 커뮤니티 게시글	LinKHU를 모르는 사람	변경 목록을 두지 않는다. 계속 알릴 기능만 기능 목록에 녹인다

두 글은 같은 릴리스를 다루지만 독자가 다르다. 스토어 글은 이미 페이지에 들어온 사람에게 목록으로 알리고, 커뮤니티 글은 아무 맥락 없는 사람에게 이게 뭔지부터 설명한다. 한쪽을 복사해 다른 쪽에 넣지 않는다.

그래서 변경 목록은 스토어 글에만 둔다 (MUST). 커뮤니티 글을 읽는 사람은 이전 버전을 모른다. (v2.8.0 업데이트)가 소개보다 먼저 오면 지난 버전을 아는 사람용 글로 읽혀 그냥 넘긴다. 커뮤니티 글의 첫 문장은 "이게 무엇인가"여야 한다 (MUST).

변경 이력이 필요한 사람은 홈페이지의 업데이트 섹션으로 간다(이슈 #190). 릴리스를 내면 자동으로 따라오므로 홍보글이 그 일을 떠맡을 이유가 없어졌다. 버전 번호는 스토어 언어다.

순서

1. 무엇이 바뀌었는지 읽는다

VERSION=$(node -p "require('./src/manifest.json').version")
cat "release-notes/v$VERSION.md"

버전은 src/manifest.json이 원본이다. 문구에 적는 번호는 여기서 가져온다.

2. 사용자 노출 변경만 고른다

### Internal 섹션은 통째로 버린다. 사용자가 화면에서 겪지 않는 변경이다.

Features와 Fixes에서도 화면에 드러나는 것만 남긴다. 3~5개. 더 늘리면 아무것도 안 읽힌다. 릴리스 노트가 10줄이어도 사용자 눈에 보이는 사건은 보통 서너 개다.

기준은 하나다 — 사용자가 그 항목을 읽고 "그래서 내가 뭘 할 수 있는데"에 답할 수 있는가.

릴리스 노트 원문	문구
색상을 디자인 토큰으로 일원화하고 주색을 역할별로 분리	버린다. 화면에서 겪는 일이 아니다
다크 테마 아이콘 생성 스크립트 추가	버린다. 결과는 "다크에서 또렷하게 보인다"로 이미 다른 줄에 있다
시스템·라이트·다크 3단계 테마 추가	남긴다. 사용자가 누를 버튼이 생겼다

3. 계속 알릴 기능을 상시 섹션으로 내린다

스토어 글의 업데이트 섹션은 다음 릴리스에서 사라진다. 계속 알릴 기능이라면 [주요 기능]이나 [편의 기능]으로 옮긴 뒤 업데이트 섹션에서 지운다.

v2.4.0의 문의하기가 그렇게 내려갔다. v2.4.0에서는 새 기능이라 업데이트 항목이었고, v2.5.0에서는 [편의 기능]의 한 줄이 되었다. 이 단계를 건너뛰면 기능이 조용히 사라진다 — 스토어 설명에 문의하기가 한 줄도 없는 채로 남는다.

두 문서 모두에서 확인한다. 커뮤니티 글에는 업데이트 섹션이 없지만 승격은 그대로 필요하다 — 오히려 커뮤니티 글에서는 상시 섹션에 녹이는 것이 그 기능을 알릴 유일한 자리다. 두 문서에서 하는 일이 이렇게 갈린다.

	스토어 글	커뮤니티 글
업데이트 섹션에서 지우기	한다	지울 섹션이 없다
[주요 기능]·[편의 기능]으로 올리기	한다	한다

숫자가 박힌 문장([지원 사이트]의 서비스 개수 등)도 이때 함께 본다. 두 문서에 모두 있다.

4. 사용자 문장으로 고쳐 쓴다

• 내부 용어를 쓰지 않는다. 디자인 토큰, 생성 스크립트, 워크플로우, 리팩터링, 스펙, 검증 — 전부 사용자 어휘가 아니다.
• 동작으로 쓴다. "테마 토글 컴포넌트 추가"가 아니라 "헤더의 버튼으로 시스템/라이트/다크를 바꿀 수 있습니다".
• 고친 것은 증상으로 쓴다. "이랬던 문제가 없어졌습니다"가 "안정성을 개선했습니다"보다 짧고 정확하다.
• 없는 기능을 만들지 않는다. 릴리스 노트에 없는 항목은 쓰지 않는다. 여기서 지어낸 문장이 스토어 심사와 사용자 기대에 그대로 남는다.
• 버전 번호를 손으로 세지 않는다. 1단계의 $VERSION을 쓴다.

5. 두 문서를 갱신한다

• docs/store-listing.md — 한국어 블록의 [vX.Y.Z 업데이트] 섹션을 교체한다. 나머지 섹션은 3단계에서 옮길 게 없으면 건드리지 않는다.
• docs/community-post.md — 버전별 변경 목록을 넣지 않는다 (MUST). 3단계에서 고른 "계속 알릴 기능"만 [주요 기능]·[편의 기능]·[지원 사이트]에 녹인다. 그럴 것이 없으면 이 문서는 이번 릴리스에 손대지 않는다. 본문과 맺음말은 그대로 둔다. 설치 안내는 홈페이지 링크(https://kangkyunghyun.github.io/LinKHU/?utm_source=everytime) 하나로 유지하고, 스토어 직링크를 다시 붙이지 않는다. 커뮤니티 유입의 상당수가 확장을 설치할 수 없는 모바일 인앱 브라우저라 스토어 페이지로 바로 보내면 설치로 이어지지 않는다. 홈페이지는 그 방문자에게 PC 설치 경로를 안내한다.

6. 검증한다

버전을 말하는 것은 스토어 글뿐이다. 커뮤니티 글에 버전이 있으면 그것이 실수다.

VERSION=$(node -p "require('./src/manifest.json').version")

# 스토어 글이 새 버전을 말하는가 (1이어야 한다)
grep -c "v$VERSION" docs/store-listing.md

# 스토어 글에 지난 버전 표기가 남아 있는가 (0줄이어야 한다)
grep -nE "v[0-9]+\.[0-9]+\.[0-9]+ 업데이트" docs/store-listing.md | grep -v "v$VERSION"

# 커뮤니티 글에 버전 표기가 새어 들어갔는가 (0줄이어야 한다)
grep -nE "v[0-9]+\.[0-9]+\.[0-9]+" docs/community-post.md

# 내부 용어가 새어 나갔는가 (0줄이어야 한다)
grep -nE "토큰|리팩터|워크플로우|스크립트|스펙|커밋|검증 추가" docs/store-listing.md docs/community-post.md

세 번째 명령이 이번에 갈린 부분이다. 예전에는 두 문서를 함께 grep -c "v$VERSION"으로 검사했는데, 커뮤니티 글이 버전을 말하지 않게 되면서 그 명령은 0을 정상으로 봐야 한다. 0이 정상인 검사는 "빠뜨린 것"과 구분되지 않으므로, 커뮤니티 글은 버전이 있으면 실패하는 검사로 바꿨다.

내부 용어 검사는 두 문서에 그대로 적용된다. 그 규칙은 변경 목록의 유무와 무관하다.

그리고 릴리스 노트와 나란히 놓고 읽는다. 지어낸 항목이 있는지는 명령으로 안 잡힌다.

하지 말 것

• ### Internal을 요약해서 넣지 않는다. 요약해도 사용자에게는 여전히 남의 일이다.
• 모든 항목을 넣지 않는다. 목록이 길수록 새 기능이 묻힌다.
• 문서를 새로 쓰지 않는다. 두 원본은 릴리스마다 제자리에서 고친다. 매번 새로 지으면 말투와 링크가 판마다 갈라진다.
• 커뮤니티 글에 변경 목록을 넣지 않는다. 읽는 사람이 이전 버전을 모른다. 변경 이력은 홈페이지의 업데이트 섹션이 맡는다. 이유는 위 표 아래에 있다.
• 커뮤니티 글에 스토어 직링크를 넣지 않는다. 착지점은 홈페이지 하나로 유지한다. 이유는 5단계에 있다.
• 스토어 대시보드에 붙여넣는 것까지 대신하지 않는다. 문서를 갱신하는 데서 끝내고, 붙여넣기는 Store Release Checklist를 따라 사람이 한다.

관련 문서

• Release Process — 버전 올리기부터 스토어 배포까지 전체 절차
• Store Release Checklist — 스토어별 제출 절차