Skip to content

Latest commit

 

History

History
103 lines (70 loc) · 6.31 KB

changeset-guide.md

File metadata and controls

103 lines (70 loc) · 6.31 KB

체인지셋 작성 규약

.changeset/*.md를 만들거나 고칠 때 따른다.

1. 독자

체인지셋은 릴리스 시 packages/jds/CHANGELOG.md로 옮겨진다. 독자는 JDS를 쓰는 소비처 개발자이고, 질문은 하나다. 이 버전으로 올리면 내 코드에 무슨 일이 생기는가.

  • 배포되는 코드가 바뀌면 소비처가 체감하지 못하더라도 한 줄은 남긴다. 릴리스 로그에 그 버전이 왜 나왔는지가 비어 있으면 안 된다.
  • 배포물에 들어가지 않는 변경(테스트, 스토리, 문서, CI)은 체인지셋을 만들지 않는다.
  • 사실은 쓰고 의도는 쓰지 않는다. 무엇이 바뀌었는지와 그 결과만 적고, 왜 그렇게 했는지와 어떤 과정을 거쳤는지는 적지 않는다.
나쁨 :read-only가 checkbox 등에서도 매칭되기 때문에 data-readonly를 사용합니다.
좋음 readonly 상태를 data-readonly 속성으로 노출합니다. 이 속성으로 스타일링하던 코드는 확인이 필요합니다.

PR/이슈 번호, 작업자 이름, 작업 순서는 쓰지 않는다.

2. 범위와 파일명

  • 컴포넌트 하나에 파일 하나. 같은 컴포넌트라도 성격이 다른 변경은 나눈다.
  • 파일명은 자동 생성 이름(fruity-cities-wait) 대신 주제를 담은 kebab-case로 쓴다.

3. bump

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

4. 구조

섹션은 이 이름과 순서로, 필요한 것만 쓴다.

---
"@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개를 넘거나 기본값을 함께 보여야 하면 표를 쓴다.

동작 변경 — 호출부 수정 없이 결과만 달라지는 것. 값이 바뀌었으면 이전 값과 새 값을 함께 적는다.

5. 문체

  • 산문은 한국어 ~합니다 체로 쓰고 문장 끝에 온점을 찍는다. 추가합니다, 제거했습니다.
  • 불릿과 표 셀은 명사형으로 끝내고 온점을 찍지 않는다. 제거, 변경, 자동 사이징, 확인 필요.
  • 한 불릿에 부연이 필요하면 문장을 새로 시작하지 말고 쉼표나 대시(—)로 이어 붙인 뒤 명사형으로 끝낸다.
  • 코드 식별자는 백틱으로 감싼다.
  • 이모지, 가운뎃점(·)은 쓰지 않는다. 나열은 쉼표로 한다.
  • 한 문장에 한 사실. "breaking change입니다" 같은 자기 분류 대신 무엇을 고쳐야 하는지를 쓴다.

6. 제출 전 확인

  • 소비처가 이 글만 읽고 코드를 고칠 수 있는가
  • 구현 의도나 과정 설명이 섞이지 않았는가
  • 소비처 영향이 없다면 없다고 밝혔는가
  • bump가 §3 표와 맞는가
  • 섹션 이름과 순서가 §4와 같은가
  • 제거한 API마다 대체재나 제거 표기가 있는가