릴리스 노트 템플릿

템플릿

대괄호 안의 모든 것은 자리표시자입니다. 그 외의 모든 것은 순서를 포함해 유지할 가치가 있습니다: 사용자는 자신에게 영향을 미치는 것을 찾으므로, 호환성이 깨지는 변경 사항이 먼저 오고 내부 작업은 전혀 표시되지 않습니다.

## [제품] [버전] - [날짜]

[이 릴리스가 무엇을 위한 것인지 한 문장으로. 일상적인 릴리스에서는 생략.]

### 호환성이 깨지는 변경 사항
- [무엇이 깨졌는지, 대신 무엇을 해야 하는지, 언제까지. 마이그레이션
  단계에 링크.]

### 새 기능
- [결과로 설명된 기능. "필터를 고정하고 재사용", "SavedView 모델
  추가됨"이 아니라.]

### 개선
- [무엇이 더 빠르거나, 더 명확하거나, 더 신뢰할 수 있게 되었는지,
  대략 얼마나.]

### 수정
- [사용자가 본 증상, 코드 내 원인이 아니라.]

섹션이 비어 있으면 제목을 삭제하세요. 비어 있는 '수정' 섹션은 아무것도 수정되지 않은 것처럼 읽히고, 아래에 아무것도 없는 제목은 독자가 페이지가 로드되지 않았다고 생각하게 만듭니다.

동일한 템플릿, 작성된 상태

실제 내용을 채우면 이렇게 보입니다. 어떤 항목도 파일, 브랜치, 티켓 번호, 사람을 언급하지 않으며, 호환성이 깨지는 변경 사항은 독자가 취해야 할 조치로 시작한다는 점에 주목하세요.

## Acme API 4.2 - 2026년 8월 20일

페이지네이션이 이제 모든 목록 엔드포인트에서 커서 기반이 됩니다.

### 호환성이 깨지는 변경 사항
- `?page=`가 모든 목록 엔드포인트에서 제거되었습니다. 이전 응답의
  `nextCursor` 값을 사용하세요. `?page=`는 2026년 10월 1일 이후
  400을 반환합니다. 마이그레이션 단계:
  acme.example/docs/pagination

### 새 기능
- 받은편지함에 저장된 뷰. 필터를 한 번 고정하면 사이드바에서
  재사용할 수 있습니다.
- webhook을 이제 단일 프로젝트로 제한할 수 있습니다.

### 개선
- 목록 엔드포인트가 대규모 계정에서 약 4배 더 빠르게
  응답합니다.
- 내보내기 작업이 멈춘 것처럼 보이는 대신 진행 상황을 보고합니다.

### 수정
- 초대된 멤버가 첫 로그인 전에 빈 대시보드를 보는 일이
  없어졌습니다.
- 내보내기의 타임스탬프가 이제 계정의 시간대를 반영합니다.

각 섹션에 무엇이 들어가는가

호환성이 깨지는 변경 사항

마감일이 포함된 유일한 섹션입니다. 무엇이 작동을 멈추는지, 대신 무엇을 해야 하는지, 그리고 언제 멈추는지 말하세요. 아직 날짜를 정하지 않았다면 아직 이 섹션을 게시하지 마세요: 날짜가 없는 호환성 파괴 변경은 긴급한 것으로 읽히며, 거짓 긴급함의 연속은 사람들이 여러분의 릴리스 노트를 무시하는 법을 배우는 방식입니다.

새 기능

여러분이 만든 객체가 아니라 결과를 설명하세요. 테스트는 그 줄이 여러분의 코드를 본 적 없는 누군가에게도 여전히 의미가 있는지입니다. '받은편지함에 저장된 뷰'는 통과합니다. 'SavedView 모델과 그 마이그레이션 추가됨'은 통과하지 못합니다.

개선

정직하게 할 수 있는 곳에서 정량화하세요. '더 빨라짐'은 거의 가치가 없으며 독자는 이를 할인해서 받아들입니다. '대규모 계정에서 약 4배 빠름'은 읽을 가치가 있고 여러분이 책임질 수 있는 기대를 설정합니다. 측정할 수 없다면 반증 가능한 방식으로 무엇이 더 나은지 말하세요.

수정

원인이 아니라 증상을 쓰세요. 사용자는 이 노트에서 자신에게 일어난 일을 찾으므로, '초대된 멤버가 빈 대시보드에 도착했다'는 찾을 수 있지만 '멤버십 캐시의 레이스 컨디션 수정'은 그렇지 않습니다.

변형

네 개의 섹션은 대부분의 릴리스에 적용됩니다. 세 가지 경우는 변경이 필요합니다:

• 모바일 앱 릴리스. 앱 스토어는 짧은 새 소식 필드를 보여주므로 스토어 목록에서 읽을 수 있는 한 문장으로 시작한 다음 전체 노트에 링크하세요. 스토어 심사도 빌드를 며칠 동안 지연시킬 수 있으므로, 노트는 병합 날짜가 아닌 릴리스 날짜로 작성하세요.
• API 릴리스. API를 버전 관리하는 것과 동일한 방식으로 노트를 버전 관리하고, 폐기 기간을 문서뿐만 아니라 노트 자체에 포함하세요. API 소비자는 자신에게 남은 시간을 정확히 알기 위해 노트를 읽습니다.
• 내부 또는 관리 도구. '개선' 섹션을 제거하고 '수정'과 병합하세요. 내부 사용자는 자신의 워크플로가 바뀌었는지 신경 쓰며, 긴 '개선' 섹션은 그것을 묻어버립니다.

이를 읽기 쉽게 유지하는 네 가지 규칙

1. 여러분의 코드를 모르는 누군가를 위해 쓰세요. 파일 이름, 브랜치 이름, 티켓 ID, 서비스 이름, 내부 코드명은 쓰지 마세요.
2. 사용자에게 보이는 효과가 없는 모든 것을 생략하세요. 의존성 업데이트, 리팩터링, CI 변경, 오타 수정은 릴리스 노트가 아니라 커밋 히스토리에 속합니다. 릴리스 노트가 죽는 가장 흔한 방식은 팀 밖의 누구도 볼 수 없는 작업으로 채워지는 것입니다.
3. 하나의 항목, 하나의 변경. 한 줄에 '그리고'라는 단어가 두 번 필요하다면 그것은 아마 두 개의 항목입니다.
4. 리듬이 '배포할 때마다'일지라도 사람들이 의지할 수 있는 리듬으로 게시하세요. 일주일에 네 번 나타났다가 두 달 동안 나타나지 않는 노트는 노이즈로 취급됩니다.

릴리스 노트 형식: 순서대로의 각 부분

형식은 순서보다 덜 중요합니다. 어떤 제목 스타일을 사용하든, 릴리스 노트를 훑어보는 독자는 같은 네 가지를 같은 순서로 원하며, 인기 있는 모든 릴리스 노트 형식은 이것의 변형입니다.

1. 버전 번호가 아니라 독자에게 무엇이 바뀌었는지를 말하는 제목. 버전은 그 아래 작은 줄에 들어가며, 날짜는 모든 로케일에서 동일하게 읽히도록 ISO 형식(2026-08-29)으로 표시됩니다.
2. 호환성이 깨지는 변경 사항과 마감일이 있는 모든 것을, 작더라도 먼저. 독자가 한 문단을 읽고 멈춘다면 이것이 그들이 필요로 했던 문단입니다.
3. 무엇이 새로운지, 문단당 하나의 항목, 결과를 첫 절에 두고 필요한 조치를(‘조치 필요 없음’ 포함) 매번 명시.
4. 수정 사항과 개선 사항, 그다음 하단에 한 줄짜리 목록으로 나머지 모든 것. 의존성 업데이트와 내부 변경은 남아 있습니다. 그것을 찾는 단 한 사람이 정말로 그것을 필요로 하기 때문입니다.

Markdown에서 이는 H2 제목, 흐릿한 버전 및 날짜 줄, 그다음 호환성 파괴·새 기능·개선·수정을 위한 H3 섹션입니다. 이메일에서는 제목을 제목줄로 한 동일한 순서입니다. changelog 위젯에서는 제목과 첫 문단이며, 나머지는 링크 뒤에 있습니다. 위의 템플릿은 그 형태를 그대로 풀어쓴 것입니다.

형태가 아닌 글쓰기 자체에 대해서는 블로그의 실제로 읽히는 릴리스 노트 작성법과 지킬 가치가 있는 릴리스 노트 모범 사례를 참조하세요.

자주 묻는 질문

릴리스 노트는 얼마나 길어야 하나요?

사용자에게 영향을 미치는 변경 사항이 요구하는 만큼이며, 그 이상은 아닙니다. 버그 수정 하나만 있는 릴리스는 두 줄이면 됩니다. 작은 릴리스를 상당한 것처럼 보이게 부풀리는 것은 사람들이 큰 것을 건너뛰도록 훈련시킵니다.

릴리스 노트와 changelog의 차이는 무엇인가요?

실제로는 이 용어들이 같은 의미로 사용됩니다. 팀이 이를 구분하는 경우, 릴리스 노트는 단일 릴리스를 설명하고 사용자를 위해 작성되는 반면, changelog는 시간에 따른 모든 릴리스의 지속적인 목록입니다. 이 템플릿은 하나의 릴리스를 다룹니다. changelog는 그것들을 최신 순으로 쌓았을 때 얻는 것입니다.

릴리스 노트에 버전 번호가 있어야 하나요?

사용자가 그것을 볼 수 있는 경우에만 그렇습니다. 버전 번호는 독자가 자신이 어느 버전에 있는지 알아야 하는 API, 라이브러리, 설치된 소프트웨어에 유용합니다. 지속적으로 배포되는 웹 앱의 경우 날짜가 더 유용합니다. 그것이 사용자가 자신의 경험과 대조할 수 있는 것이기 때문입니다.

누가 이를 작성해야 하나요?

무엇이 바뀌었는지 아는 사람, 보통 그것을 병합한 엔지니어이며, 목소리를 담당하는 사람이 편집합니다. 이를 작업 외부의 누군가에게 완전히 맡길 때의 실패 패턴은 변경 사항이 아닌 티켓을 설명하는 노트입니다.