지킬 가치가 있는 릴리스 노트 모범 사례

정말로 중요한 릴리스 노트 모범 사례는 결과가 뒤따르는 것들이다. 병합 시점에 항목을 쓰고, 누가 영향을 받는지 이름을 밝히고, 필요한 조치가 없더라도 그것을 명시하고, 파괴적 변경에는 날짜를 붙이고, 변경 사항마다 영구적인 항목 하나를 유지하고, 결과별로 묶고, 지루한 섹션을 남겨두는 것. 이들 각각은 독자의 실제 행동을 바꾼다. 이 주제에 관한 나머지 조언들은 대부분 노트가 보이는 모습만 바꿀 뿐이다.

릴리스 노트 모범 사례를 검색하면 문체에 대한 조언이 나온다. 명확하게 쓰라, 간결하게 쓰라, 쉬운 언어를 쓰라, 스크린샷을 추가하라. 어느 것도 틀리지 않았지만 어느 것도 아무것도 바꾸지 않는다. 일부러 불명확하게 쓰려고 자리에 앉은 팀은 없기 때문이다. 아래의 관행들에는 각각 건너뛸 때 치러야 할 대가가 따라온다. 실패 사례가 붙어 있지 않은 관행은 그저 취향일 뿐이기 때문이다.

릴리스 노트의 모범 사례는 무엇인가

릴리스 시점이 아니라 병합 시점에 항목을 써라. 건너뛸 때의 대가: 커밋 히스토리로부터 릴리스를 재구성하는 사람은 실제로 변경을 만든 사람이 아니며, 의도를 추측하게 된다. 몇 주 후에 쓰인 항목이 “여러 가지 개선 사항”이라고만 말하는 항목이다.

누가 영향을 받는지 이름으로 밝혀라. “Business 요금제 사용 팀”, “v1 내보내기 API를 사용하는 모든 사람”, “Postgres 14에서 셀프 호스팅하는 설치본”. 건너뛸 때의 대가: 모든 독자가 자신에게 해당되는지 직접 판단해야 하고, 대부분은 아니라고 결정해버린다.

필요한 조치를, 없을 때조차, 명시하라. 건너뛸 때의 대가: 지원팀이 똑같은 질문에 마흔 번 답하게 되고, 묻지 않은 독자들은 그냥 무언가 필요하다고 짐작하고 미뤄버린다.

파괴적 변경에는 릴리스 번호가 아니라 날짜를 붙여라. “v5에서 제거됨”은 v5가 언제 나올지 모르는 사람에게는 아무 의미가 없다. “11월 1일부터 작동하지 않습니다”는 달력에 적어둘 수 있는 날짜다. 건너뛸 때의 대가: 기한이 지나고 나서야 그것을 알게 된다. 무엇이 파괴적 변경으로 취급되는지, 그리고 그것을 출시하기 위한 체크리스트는 파괴적 변경이란 무엇인가에 있다.

변경 사항마다 링크 가능한 영구 항목 하나를 유지하라. 이메일은 보관소가 아니고 Slack 메시지는 참고 자료가 아니다. 건너뛸 때의 대가: 여섯 달 뒤에는 여러분 자신을 포함해서 “이게 언제 바뀌었지”에 아무도 답할 수 없다. 이메일에도 여전히 역할이 있으며, 제품 업데이트 이메일 템플릿에서 다룬다. 항목을 대체하는 대신 그것을 가리킨다.

시스템이 아니라 결과별로 묶어라. 건너뛸 때의 대가: 독자가 어떤 섹션이 자신에게 중요한지 알아내려면 여러분의 아키텍처를 머릿속에 담고 있어야 한다. 여기서 따라 나오는 순서 배치 방식은 릴리스 노트를 쓰는 방법에 있다.

지루한 섹션을 유지하라. 의존성 업데이트와 내부 변경 사항은 맨 아래에 한 줄씩 남겨둔다. 건너뛸 때의 대가: 보안팀, 컴플라이언스 검토자, 버전 불일치를 디버깅하는 사람 모두가 유일한 출처를 잃는다. 이 부분을 가장 자주 틀리는 항목은 수정 사항이며, 버그 수정 릴리스 노트는 독자가 조치해야 하는지 알 수 있도록 그것을 쓰는 방법을 보여준다.

체인지로그 모범 사례는 무엇이고, 무엇이 다른가

체인지로그는 참고 자료이므로, 그 관행들은 설득이 아니라 완전성과 구조에 관한 것이다. 중요한 네 가지는 다음과 같다.

• 줄마다 고정된 항목 유형. Added, Changed, Deprecated, Removed, Fixed, Security. 이것은 하우스 스타일이 아니라 필터다. 누군가 “파괴적 변경만” 요청할 수 있게 해주는 것이다. Keep a Changelog 관례가 보통의 출처다.
• 미출시 섹션. 병합과 릴리스 사이에 항목들이 머무는 곳. 이것이 없으면 팀은 항목을 늦게 쓰게 된다.
• ISO 날짜. 2026-08-28이지, 28/08/26이 아니다. 후자는 독자에 따라 서로 다른 날을 의미한다.
• 커밋이 아니라 변경 사항마다 항목 하나. 하나의 버그를 고친 세 개의 커밋은 하나의 항목이다.

이 두 성과물은 체인지로그 대 릴리스 노트에서 제대로 비교된다. 짧게 말하면, 체인지로그의 관행은 완전성을 지키고 릴리스 노트의 관행은 주의를 지킨다. 엔터프라이즈 고객을 위한 비공개 릴리스 노트는 고객이 더 이상 모두 같은 빌드에 있지 않게 되었을 때만 나타나는 이것의 버전을 다룬다. 같은 완전성과 주의라는 목표지만, 모두에게 한꺼번에 방송하는 대신 계정별로 조정된다.

유행만 좇는 세 가지

항목 유형으로서의 이모지. 로켓과 렌치는 분류 체계가 아니다. 깔끔해 보이지만 필터링도, 정렬도, 스크린 리더로 유의미하게 읽히지도 않는다. 단어를 쓰고, 이모지를 원한다면 단어 뒤에 붙여라.

호스팅 제품의 헤드라인으로 쓰이는 시맨틱 버전 번호. 시맨틱 버저닝은 API 호환성에 대한 약속이다. 아무도 자신의 버전을 선택하지 않는 SaaS 제품에서 헤드라인에 들어간 버전 번호는 뉴스로 치장한 내부 정리용 라벨일 뿐이다. 시맨틱 버전은 체인지로그 안에 두고 발표 문구에서는 빼라.

내용과 무관하게 일정에 맞춰 발행하기. 아무 내용도 없는 월간 노트는 사람들에게 여러분의 노트가 소음이라고 가르친다. 할 말이 있을 때 발행하라. 나머지는 체인지로그가 담당한다.

실제로 어려운 것 하나

체인지로그와 발표 문구를 두 번 쓰지 않으면서 서로 맞춰 유지하는 일이다.

대부분의 팀은 하나의 페이지로 시작해서, 독자층이 갈라지면 나누고, 그러고 나서 둘 중 하나를 조용히 썩게 내버려둔다. 보통은 체인지로그다. 그것에는 기한이 붙어 있지 않기 때문이다. 벗어나는 방법은 규율이 아니라 구조에 있다. 항목을 유형, 날짜, 대상 독자를 가진 데이터로 유지하고, 두 표면 모두를 그 데이터의 렌더링으로 다루는 것이다. 우리의 체인지로그 도구 정리는 우리가 경쟁하는 도구를 포함해 그것을 위해 무엇이 존재하는지를 다루며, Beamer 대안 페이지는 대부분의 팀이 출발점으로 삼는 위젯과의 정직한 비교다.

릴리스 노트 템플릿은 항목들이 이미 존재할 때 선별 단계가 이루어지는 곳이다.

하나만 채택한다면

병합 시점에, 고정된 형식으로, 유형을 붙여서 항목을 써라. 이 페이지의 다른 모든 관행은 이것이 자리 잡고 나면 더 쉬워지고, 그것 없이는 어느 것도 살아남지 못한다.

FAQ

릴리스 노트에는 스크린샷이 있어야 하는가? 실제로 바뀐 것이 사용되는 모습만 넣어라. 아무도 방문한 적 없는 설정 페이지의 스크린샷은 정보가 아니라 스크롤만 늘린다. 결과와 영향받는 독자를 이름으로 밝힌 텍스트가, 둘 다 보여주지 않는 이미지보다 낫다.

파괴적 변경에 대한 릴리스 노트는 어떻게 쓰는가? 날짜를 먼저, 영향받는 호출자를 두 번째로, 필요한 조치를 세 번째로, 이전 방법을 네 번째로 둔다. 버전 번호로 시작하지 마라. 예시 항목과 함께 전체 형식은 파괴적 변경이란 무엇인가에 있다.

릴리스 노트는 엔지니어링이 써야 하는가, 마케팅이 써야 하는가? 변경을 만든 엔지니어가 병합 시점에 초안을 쓰고, 그것을 낯선 사람처럼 읽는 누군가가 편집해야 한다. 둘 중 하나만으로는 고객이 실행에 옮길 수 있는 노트가 나오지 않는다.

이상적인 릴리스 노트 형식은 무엇인가? 기한이 있는 항목을 먼저, 다음으로 새로운 기능, 다음으로 개선 사항, 그리고 나머지는 한 줄씩 목록으로. 릴리스 노트 템플릿이 그 형식을 채워 넣는 페이지로 만든 것이다.

이 글의 기술적 내용은 독립적으로 검토되지 않았습니다. 잘못된 부분이 있으면 알려 주세요. 바로잡겠습니다.

changeloop 관련 페이지: 릴리스 노트 템플릿, changelog 도구 비교