실제로 읽히는 릴리스 노트를 쓰는 방법

사람들이 실제로 읽는 릴리스 노트를 쓰려면, 항목마다 하나의 질문에 답하라. 독자가 이전에는 할 수 없었지만 지금은 할 수 있게 된 것은 무엇이며, 그것에 대해 독자가 해야 할 일은 무엇인가. 기한이 있는 내용은 항상 맨 앞에 두고, 누가 영향을 받는지 이름을 밝히고, 정말로 아무것도 할 필요가 없다면 “조치가 필요 없습니다”라고 말하고, 특별히 할 말이 없는 릴리스는 건너뛰어라. 이 페이지의 나머지 내용은 모두 이 규칙을 적용한 것이다.

버그 수정 및 성능 개선.

모든 제품이 이런 문구를 내보낸 적이 있다. 원인은 게으름인 경우가 드물다. 이것은 릴리스 노트를 내부 시점에서, 즉 이미 두 주 동안 diff 속에서 살아온 사람이, 낯선 사람이라면 어느 부분에 신경을 쓸지 더는 알아차리지 못하는 상태에서 쓸 때 나오는 결과다. 더 나은 어조로는 이 문제가 고쳐지지 않는다. 질문에 답하는 것만이 고친다.

릴리스 노트에는 무엇을 포함해야 하는가

릴리스 노트는 언급할 가치가 있는 각 변경 사항에 대해, 독자가 이제 무엇을 할 수 있는지, 누구에게 해당되는지, 그것에 대해 무엇을 해야 하는지(“아무것도 없음”을 포함해서), 그리고 기한이 있는 항목이라면 언제부터 적용되는지를 포함해야 한다. 내부 티켓 번호, 팀만 아는 컴포넌트 이름, 그리고 헤드라인 역할만 하는 버전 번호는 포함하지 않아야 한다.

릴리스 노트와 체인지로그 항목의 구분이 있기에 이 목록이 가능해진다. 체인지로그는 모든 것을 담아 두므로, 노트는 무언가를 빼도 괜찮다. 항목 유형별 주석 달린 샘플은 릴리스 노트 예시에 모아 두었다.

모든 항목이 답해야 하는 질문

독자가 이전에는 할 수 없었지만 지금은 할 수 있게 된 것은 무엇이며, 그것에 대해 무엇을 해야 하는가?

어떤 항목이 이 질문에 답할 수 없다면, 그것은 릴리스 노트가 아니라 체인지로그에 속한다. 두 부분 모두 중요하다. 앞부분은 가치이고, 뒷부분은 팀들이 흔히 잊는 부분이며, 빠졌을 때 지원 티켓을 만들어내는 부분이다.

뒷부분이 실제로 일을 하는 두 가지 예시다.

• “기존 웹훅은 11월 1일까지 계속 작동합니다. 그 이후에는 서명되지 않은 페이로드가 거부됩니다.”
• “조치가 필요 없습니다. 기존 내보내기 파일은 다음에 열 때 자동으로 다시 인코딩됩니다.”

두 번째 예시는 “조치가 필요 없습니다”라고 명시적으로 말한다. 그 문장은 매번 써넣을 가치가 있다. 그것을 찾지 못한 독자는 최악의 상황을 가정하기 때문이다.

릴리스 노트는 어떤 순서로 배치해야 하는가

시스템의 어느 부분이 바뀌었는지가 아니라, 독자에게 미치는 결과에 따라 순서를 정하라. API, 대시보드, 모바일, 인프라로 묶는 것은 여러분의 조직도이지, 독자의 문제가 아니다.

1. 파괴적 변경과 기한이 있는 모든 것. 작은 것이라도 항상 맨 먼저 둔다. 독자가 한 줄만 읽고 멈춘다면, 이 줄은 반드시 읽었어야 할 줄이다. 기한이 서비스 종료일이라면, 그 항목은 비추천 공지처럼 읽혀야 한다.
2. 독자가 원할 만한 새로운 것. 문단마다 하나씩, 첫 절에 결과를 담는다.
3. 더 나아진 것. 신고되었던 수정 사항, 완화된 제한, 느렸던 부분들.
4. 그 밖의 모든 것, 목록으로. 의존성 업데이트, 내부 리팩터링, 소소한 문구 변경. 한 줄씩. 이 섹션을 읽는 사람은 거의 없지만, 그래도 있어야 한다. 그것을 찾는 사람에게는 정말로 필요한 정보이기 때문이다.

다시 쓰기

이전:

v4.2.0 POST /exports 엔드포인트가 부하 상황에서 간헐적으로 500을 반환하던 문제를 수정했습니다. export worker를 리팩터링했습니다. node-pg를 8.11로 업데이트했습니다. CSV serializer의 오류 처리를 개선했습니다.

이후:

대규모 계정에서 더 이상 내보내기가 실패하지 않습니다. 약 5만 행이 넘는 계정은 내보내기를 시작할 때 500 오류를 받을 수 있었고, 월말에 특히 자주 발생했습니다. 이제 수정되었고, 크기와 무관하게 모든 내보내기가 실패하는 대신 스스로 재시도합니다. 조치가 필요 없으며, 지난 한 주 동안 실패한 내보내기는 그저 다시 실행하기만 하면 됩니다.

4.2.0의 다른 변경 사항: node-pg 8.11, 더 명확해진 CSV serializer 오류 메시지.

같은 릴리스다. 두 번째 버전은 영향을 받은 계정, 가장 심했던 시기, 무엇이 바뀌었는지, 그리고 무엇을 해야 하는지를 명시한다. 의존성 업데이트가 사라진 것이 아니라, 그저 헤드라인이 되기를 멈췄을 뿐이다. 릴리스 노트 모범 사례 글에는 이 다시 쓰기가 따르고 있는 나머지 규칙들이, 각각 건너뛸 때 어떤 대가가 따르는지와 함께 담겨 있다.

삭제할 가치가 있는 것들

• “저희는 발표하게 되어 매우 기쁩니다.” 독자는 아직 기쁘지 않다. 그 기쁨은 다음 문장에서 스스로 얻어내야 한다.
• 내부 티켓 번호. PROJ-4471은 여러분의 트래커 밖에서는 아무 의미가 없다. 참조가 필요하다면 문서 페이지를 링크하라.
• 팀만 사용하는 컴포넌트 이름. “ingest pipeline”의 이름을 바꿨다면 “가져오기”라고 말하라.
• 유일한 헤드라인 역할을 하는 버전 번호. v4.2.0은 요약이 아니라 정리용 라벨일 뿐이다.
• 아무도 방문한 적 없는 설정 페이지의 스크린샷. 실제로 바뀐 것이 사용되는 모습을 보여줘라.

릴리스 노트는 얼마나 자주 발행해야 하는가

일정에 맞춰서가 아니라, 무언가 일어났을 때 발행하라. 릴리스마다 도착하는 노트는 모두가 그것을 무시하도록 훈련시킨다. 무언가 일어났을 때 도착하는 노트는 열어보게 된다. 아무 노트도 없이 릴리스를 내보내고, 그 항목들을 읽을 가치가 있는 헤드라인이 나올 다음 묶음으로 넘기는 것도 괜찮고, 대개는 그것이 맞다.

체인지로그는 여전히 그 모든 것을 기록한다. 그것이 역할 분담이다. 체인지로그는 완전하고, 노트는 선별적이다. 체인지로그를 진행하는 동안 구조화된 상태로 유지한다면, 노트를 쓰는 일은 고고학이 아니라 선별과 다시 쓰기가 된다.

릴리스 노트 템플릿은 우리가 선별 단계에서 사용하는 형식이며, 체인지로그 예시는 그 체인지로그가 충분히 훌륭해서 노트를 도출할 수 있는 팀들의 항목들을 모아 놓았다.

이 모든 것은 완전히 통제할 수 있는 페이지, 길이 제한이 없고 링크가 작동하는 페이지를 전제로 한다. 모바일 앱 릴리스 노트는 그 표면이 앱스토어나 플레이스토어 목록일 때 무엇이 달라지는지를 다룬다. 긴급 릴리스 노트는 또 다른 예외를 다룬다. 평소의 작성 과정을 따를 시간이 전혀 남지 않았을 때 무엇이 달라지는지다.

발행 전 테스트 하나

2주간 휴가를 다녀와서 40초밖에 시간이 없는 사람이라고 생각하고 노트를 읽어보라. 그 시간 안에 자신에게 무언가 요구되는 것이 있는지 없는지를 알 수 없다면, 그 노트는 아무리 정확해도 아직 완성된 것이 아니다.

FAQ

릴리스 노트는 얼마나 길어야 하는가? 결과에 영향을 미치는 변경 사항이 필요로 하는 만큼, 그 이상은 안 된다. 파괴적 변경 하나와 개선 사항 두 개가 있는 릴리스는 세 문단이면 충분하다. 조용한 릴리스를 부풀려 그럴듯하게 보이려는 것이야말로 독자가 노트를 건너뛰도록 가르치는 방법이다.

릴리스 노트는 누가 써야 하는가? 변경 사항을 이해하는 사람이 쓰고, 그것을 모르는 사람이 편집해야 한다. 엔지니어는 무엇이 바뀌었는지 알고, 편집자는 낯선 사람이 무엇을 오해할지 안다. 엔지니어가 아직 기억하고 있는 병합 시점에 항목을 써두는 관행이 이 작업을 저렴하게 만든다.

릴리스 노트에는 버그 수정도 포함해야 하는가? 그렇다. 누군가 신고했거나 직접 겪은 것이라면. 원인이 아니라 독자가 목격한 증상을 서술하라. “5만 행이 넘는 내보내기가 실패했습니다”는 독자가 알아보는 버그 수정이지만, “export worker의 경쟁 조건을 수정했습니다”는 커밋 메시지다.

릴리스 노트와 체인지로그의 차이는 무엇인가? 체인지로그는 완전하고 계속 이어지는 기록이며, 릴리스 노트는 아직 관심을 가질지 결정하지 않은 사람들을 위해 쓰인, 하나의 릴리스에 대한 선별된 메시지다. 더 자세한 답은 체인지로그 대 릴리스 노트에 있다.

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

changeloop 관련 페이지: 릴리스 노트 템플릿, changelog 예시