모든 종류의 변경에 쓸 수 있는 릴리스 노트 예시

가장 좋은 릴리스 노트 예시는 짧고, 누가 영향을 받는지 밝히고, 다음에 무엇을 해야 하는지 말한다. 아래에는 앞으로 내보낼 변경의 종류마다 예시를 하나씩, 그것이 효과적인 이유와 함께 실었다. 형태를 그대로 가져다 쓰고 내용만 여러분의 사실로 바꾸면 된다.

모든 예시는 Tidepool이라는 가상의 청구서 앱을 위해 지어낸 것이다.

좋은 릴리스 노트 예시들은 무엇이 공통적인가

무엇이 바뀌었는지, 그리고 그에 대해 해야 할 일이 있다면 무엇인지를 사용자의 언어로 알려준다. 변경의 종류마다 맡은 역할이 다르므로 형태도 조금씩 달라진다.

좋은 새 기능 노트는 어떤 모습인가

좋은 기능 노트는 독자가 이제 할 수 있는 일로 시작하고, 그것을 받는 요금제나 역할을 밝힌다. 구현 이야기는 건너뛴다.

고객의 언어로 청구서를 보내세요. 이제 고객마다 언어를 선택할 수 있으며, 그 고객의 청구서, 알림 메일, 결제 페이지가 선택한 언어를 따릅니다. 프랑스어, 독일어, 스페인어, 포르투갈어를 모든 요금제에서 사용할 수 있습니다. 고객 페이지의 결제 환경설정에서 설정하세요.

헤드라인은 독자가 소리 내어 말할 법한 문구이고, 본문은 범위와 위치를 알려준다. 굵은 글씨 줄만 훑어본 독자도 무엇이 출시되었는지 안다. 더 넓은 방법론은 릴리스 노트를 쓰는 방법에 있다.

좋은 개선 노트는 어떤 모습인가

개선 노트는 독자가 체감할 변경을 설명하고, 측정한 수치가 있다면 그것을 붙인다. 수치가 없다면 독자가 더는 하지 않아도 되는 일을 말한다.

청구서 목록이 약 세 배 빨리 열립니다. 청구서가 5,000건이 넘는 계정은 목록이 뜨기까지 약 9초를 기다려야 했습니다. 이제 약 3초 만에 열립니다. 조치가 필요 없습니다.

“성능 개선”은 독자에게 아무것도 알려주지 않지만, 9초 대 3초는 월요일 아침에 직접 확인해 볼 수 있는 주장이다. 마지막의 “조치가 필요 없습니다”는 모든 독자가 가진 질문에 답한다.

좋은 버그 수정 노트는 어떤 모습인가

버그 수정 노트는 코드의 원인이 아니라 사용자가 본 증상을 설명하고, 다시 해야 할 일이 있는지를 말한다. 아무도 눈치채지 못한 수정은 하단의 목록에 넣어도 된다.

수정됨: 알림 메일이 마감일에 두 번 발송되던 문제. 청구서의 마감일이 월말인 경우 일부 고객이 똑같은 알림을 두 번 받았습니다. 이 문제는 수정되었습니다. 이미 발송된 알림은 영향받지 않으며, 다시 보낼 필요도 없습니다.

헤드라인이 “수정됨”으로 시작하므로 훑어보는 사람이 한눈에 분류할 수 있고, 실제 조건(월말)이 바로 뒤따른다.

파괴적 변경의 릴리스 노트는 어떻게 쓰는가

파괴적 변경 노트는 날짜와 영향받는 대상으로 시작하고, 같은 항목 안에 마이그레이션을 함께 담는다. 독자가 놓쳐서는 안 되는 유일한 항목이므로 릴리스 노트의 맨 처음에 놓는다.

2026년 12월 1일부터 웹훅 서명이 필수가 됩니다. 그 날짜부터 Tidepool은 서명되지 않은 웹훅 페이로드를 보내지 않습니다. Tidepool-Signature 헤더를 확인하지 않고 웹훅을 받는 모든 분이 해당됩니다. 마이그레이션하려면 설정, 개발자 메뉴의 시크릿으로 헤더를 검증하세요. 이미 서명을 검증하고 있다면 조치가 필요 없습니다.

날짜가 헤드라인에 있어서 훑어보아도 살아남는다. 영향받는 대상은 그들이 하는 일로 지칭하고, 마지막 문장은 이미 문제없는 사람들을 놓아주므로 지원 부담이 줄어든다. 변경이 해당되는지 판단하는 방법은 파괴적 변경 가이드에서 다룬다.

보안 수정 노트는 어떤 모습인가

보안 노트는 무엇이 노출되었는지, 누군가 악용했는지, 누가 영향을 받는지, 그리고 그들이 무엇을 해야 하는지를 말한다. 사실에 충실하고 차분하게 쓴다.

보안: 비밀번호 재설정 링크가 재사용될 수 있었습니다. 2026년 9월 3일부터 17일까지, 비밀번호 재설정 링크가 한 번 사용된 뒤에도 유효한 상태로 남아 있었습니다. 악용된 흔적은 발견하지 못했습니다. 문제는 수정되었으며, 남아 있던 모든 재설정 링크는 무효화되었습니다. 그 기간에 재설정을 요청하셨다면 새 링크를 요청해 주세요.

정확한 기간이 있어서 독자가 자신의 노출 여부를 판단할 수 있고, 악용 여부에 대한 문장은 누구나 가장 먼저 던지는 질문에 답한다. “잠재적인 문제”라는 표현은 은폐처럼 읽히므로, 아는 것을 그대로 말하라.

비추천 공지는 어떻게 쓰는가

비추천 공지는 제거되는 대상을 밝히고, 확정된 종료일을 알리고, 대체 수단을 가리킨다.

v1 청구서 엔드포인트는 비추천되었으며 2027년 3월 1일에 종료됩니다. GET /v1/invoices는 2027년 3월 1일까지 계속 작동하고, 그 이후에는 410 Gone을 반환합니다. 같은 필드에 currency가 추가된 GET /v2/invoices를 사용하세요. 이제 v1 응답에는 종료일이 담긴 Sunset 헤더가 포함됩니다. 나란히 비교한 마이그레이션 가이드는 문서에 있습니다.

영향받는 사람들이 검색하는 것이 엔드포인트 이름이므로 헤드라인에 넣었고, 대체 수단은 제거 소식 바로 옆에 놓았다. Sunset 헤더는 어떤 호출이 아직 예전 버전을 쓰는지 개발자에게 알려준다. 더 자세한 내용은 API 비추천 처리에 있다.

앱스토어 릴리스 노트는 어떤 모습인가

앱스토어 노트는 평이한 두세 문장이다. 대부분의 사람은 첫 줄만 읽기 때문이다. 사용자가 알아차릴 변경으로 시작하라.

종이 영수증을 스캔하면 Tidepool이 금액, 날짜, 거래처를 채워 줍니다. 이제 다크 모드가 휴대폰 설정을 따릅니다. 알림에서 청구서를 열 때 앱이 종료되던 문제도 수정했습니다.

가장 유용한 변경이 먼저 나오고, 수정 항목은 앱이 종료되던 상황을 구체적으로 짚는다. 버전 번호도, “버그 수정 및 개선”도 없다. 스토어별 규칙은 모바일 앱 릴리스 노트에서 다룬다.

내부 릴리스 노트에는 무엇이 들어가야 하는가

내부 노트는 지원과 영업을 위한 버전이다. 공개 노트가 생략하는 것, 즉 무엇을 말해야 하고 무엇을 약속하지 말아야 하는지를 더한다.

다국어 청구서가 오늘 출시되었습니다(전 요금제). 지원: 고객은 결제 환경설정에서 언어를 설정하며, 기존 청구서는 원래 언어를 유지합니다. 이탈리아어는 아직 지원되지 않습니다. 영업: 모든 요금제에서 열려 있으므로 업그레이드 상품으로 내세우지 마세요.

각 대상이 자기 몫의 이름 붙은 줄을 받고, 고객이 묻기 전에 경계(“이탈리아어는 아직 지원되지 않습니다”)를 그어 둔다. 형식과 채널은 내부용 릴리스 노트 글에서 다룬다.

나쁜 릴리스 노트는 어떻게 고쳐 쓰는가

나쁜 릴리스 노트는 독자가 얻는 것이 아니라 팀이 한 일을 나열한다. 결과를 앞으로 옮기고 내부 용어를 지우면 고칠 수 있다.

이전:

v3.8.1 알림 스케줄러를 리팩터링했습니다. ReminderJob의 race condition을 수정했습니다. bull을 4.12로 업데이트했습니다. 기타 개선.

이후:

알림 메일이 더 이상 두 번 나가지 않습니다. 마감일이 월말인 청구서를 가진 고객이 알림을 두 번 받을 수 있었습니다. 이 문제는 수정되었고, 이미 발송된 알림을 다시 보낼 필요는 없습니다. 조치가 필요 없습니다.

3.8.1의 다른 변경 사항: bull을 4.12로 업데이트.

의존성 업데이트는 하단의 한 줄로 내려갔고, race condition은 고객이 알아볼 수 있는 증상이 되었다.

릴리스마다 릴리스 노트를 일관되게 유지하려면

변경이 병합될 때 항목마다 초안을 쓰고, 출시하기 전에 사람이 승인하게 하라.

Changeloop도 이렇게 동작한다. 병합된 pull request마다 AI로 항목의 초안을 만들고, 사람이 승인할 때까지 보류해 둔다. 승인 단계가 바로 편집자가 위의 규칙을 적용하는 자리다. 형식을 먼저 정하고 싶다면 릴리스 노트 템플릿에서 시작하고, 완성된 페이지가 어떤 모습인지는 체인지로그 예시를 보라.

FAQ

새 릴리스 노트란 무엇인가? 새 릴리스 노트는 제품의 최신 릴리스와 함께 발행되는 메시지로, 무엇이 바뀌었고 사용자가 무엇을 해야 하는지 설명한다. 기능, 개선, 수정, 파괴적 변경을 다룬다.

릴리스 노트와 체인지로그의 차이는 무엇인가? 체인지로그는 전체 이력을 원하는 누구나 볼 수 있게 모든 것을 담는다. 릴리스 노트는 거기서 골라 쓴다. 릴리스 하나에 대해, 그것이 자신에게 중요한지 판단하려는 독자를 위해 쓴다. 더 자세한 비교는 체인지로그 대 릴리스 노트에 있다.

릴리스 노트는 무슨 뜻인가? 릴리스 노트는 릴리스에서 무엇이 바뀌었는지 사용자에게 알려준다. 앱스토어의 “새로운 기능” 문구부터 회사 웹사이트의 한 페이지까지, 무엇이 출시되었는지 설명하는 모든 것을 가리킨다.

릴리스 노트 항목 하나는 얼마나 길어야 하는가? 대부분의 항목은 두세 문장에서 네 문장이면 충분하다. 결과, 영향받는 대상, 해야 할 일이다. 파괴적 변경이나 보안 수정은 날짜나 마이그레이션이 필요하므로 더 길어질 수 있다.

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

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