.changeset/*.md를 만들거나 고칠 때 따른다.
체인지셋은 릴리스 시 packages/jds/CHANGELOG.md로 옮겨진다. 독자는 JDS를 쓰는 소비처 개발자이고, 질문은 하나다. 이 버전으로 올리면 내 코드에 무슨 일이 생기는가.
- 배포되는 코드가 바뀌면 소비처가 체감하지 못하더라도 한 줄은 남긴다. 릴리스 로그에 그 버전이 왜 나왔는지가 비어 있으면 안 된다.
- 배포물에 들어가지 않는 변경(테스트, 스토리, 문서, CI)은 체인지셋을 만들지 않는다.
- 사실은 쓰고 의도는 쓰지 않는다. 무엇이 바뀌었는지와 그 결과만 적고, 왜 그렇게 했는지와 어떤 과정을 거쳤는지는 적지 않는다.
| 나쁨 | :read-only가 checkbox 등에서도 매칭되기 때문에 data-readonly를 사용합니다. |
| 좋음 | readonly 상태를 data-readonly 속성으로 노출합니다. 이 속성으로 스타일링하던 코드는 확인이 필요합니다. |
PR/이슈 번호, 작업자 이름, 작업 순서는 쓰지 않는다.
- 컴포넌트 하나에 파일 하나. 같은 컴포넌트라도 성격이 다른 변경은 나눈다.
- 파일명은 자동 생성 이름(
fruity-cities-wait) 대신 주제를 담은 kebab-case로 쓴다.
JDS는 0.x이므로 major는 쓰지 않는다. 판단이 갈리면 소비처 코드가 그대로 동작하는지를 기준으로 삼는다. 안 되면 minor다.
여기서 소비처 계약은 공개 API, 소비처가 쓰던 DOM 속성과 role, 렌더 엘리먼트, 상호작용을 말한다. 한 변경이 아래 표의 여러 행에 걸치면 minor 행이 우선한다. 접근성 개선이나 스타일링 엔진 교체, 의존성 업데이트라도 이 계약을 바꾸면 minor다. 반대로 기존 prop이 받는 값이 늘어나는 것은 하위호환이므로 patch다.
| 변경 | bump |
|---|---|
| 컴포넌트, prop, 타입, export, prop 값의 제거 또는 이름 변경 | minor |
| prop 타입이 좁아짐, 필수 prop 추가 | minor |
소비처가 쓰던 DOM 속성, role, 렌더 엘리먼트 변경 |
minor |
| 컴포넌트 신규 추가 | minor |
| 공개 유틸, 훅, 진입점 신규 추가 | minor |
| 하위호환 prop, 옵션, 타입, 아이콘 추가, prop 타입이 넓어짐 | patch |
| 버그 수정, 토큰 값 조정 | patch |
| 소비처 계약을 바꾸지 않는 접근성 개선 | patch |
| 소비처 계약을 바꾸지 않는 스타일링 엔진 마이그레이션, 내부 컴포넌트 정리 | patch |
| 소비처가 체감하지 않는 의존성 업데이트 | patch |
섹션은 이 이름과 순서로, 필요한 것만 쓴다.
---
"@jects/jds": minor
---
**ComponentName**
무엇이 바뀌었고 소비처가 무엇을 해야 하는지 1~3문장.
**소비처 영향 (코드 수정 필요)**
| AS-IS | TO-BE |
| ----- | ----- |
| ... | ... |
(diff 블록)
**추가**
- 하위호환으로 늘어난 API
**동작 변경 (코드 수정 불필요)**
- 코드는 그대로지만 결과가 달라지는 것- 이름 줄은
**Card**처럼 굵게만 쓴다. 콜론을 붙여 요약을 이어 쓰지 않는다. 여러 서브컴포넌트를 묶었으면**Badge (ContentBadge / DotBadge)**로 범위를 밝힌다. - 요약 문단은 필수다. 표부터 시작하지 않는다.
- 마크다운 헤딩(
###)은 쓰지 않는다. CHANGELOG에 병합될 때 계층이 깨진다. - 항목이 한두 개면 섹션 제목 없이 요약과 불릿으로 끝낸다. 신규 컴포넌트도 제목 없이 요약, prop 목록, 예시만 쓴다.
소비처 영향 — 제거되거나 이름이 바뀐 것을 AS-IS | TO-BE 2열 표로 보여준다. 대체재가 없으면 TO-BE에 제거와 사유를 짧게 적는다. 상호 배타 관계나 필수 조합처럼 표에 안 담기는 조건은 아래 문장으로 덧붙인다.
마이그레이션 코드 — 소비처 영향이 있으면 반드시 ```diff 블록으로 보여준다. AS-IS / TO-BE 두 블록으로 나누지 않는다. 구조가 통째로 바뀌어도 이전 블록 전체를 -, 이후를 +로 적는다. 성격이 다른 마이그레이션이 여럿이면 블록을 나누고 각각 앞에 한 줄 설명을 붙인다.
추가 — 새로 쓸 수 있게 된 것만. prop은 이름, 기본값, 용도를 한 줄로. 4개를 넘거나 기본값을 함께 보여야 하면 표를 쓴다.
동작 변경 — 호출부 수정 없이 결과만 달라지는 것. 값이 바뀌었으면 이전 값과 새 값을 함께 적는다.
- 산문은 한국어
~합니다체로 쓰고 문장 끝에 온점을 찍는다.추가합니다,제거했습니다. - 불릿과 표 셀은 명사형으로 끝내고 온점을 찍지 않는다.
제거,변경,자동 사이징,확인 필요. - 한 불릿에 부연이 필요하면 문장을 새로 시작하지 말고 쉼표나 대시(
—)로 이어 붙인 뒤 명사형으로 끝낸다. - 코드 식별자는 백틱으로 감싼다.
- 이모지, 가운뎃점(
·)은 쓰지 않는다. 나열은 쉼표로 한다. - 한 문장에 한 사실. "breaking change입니다" 같은 자기 분류 대신 무엇을 고쳐야 하는지를 쓴다.
- 소비처가 이 글만 읽고 코드를 고칠 수 있는가
- 구현 의도나 과정 설명이 섞이지 않았는가
- 소비처 영향이 없다면 없다고 밝혔는가
- bump가 §3 표와 맞는가
- 섹션 이름과 순서가 §4와 같은가
- 제거한 API마다 대체재나
제거표기가 있는가