소프트웨어 릴리스 노트란 무엇이며 무엇을 담아야 하는가

소프트웨어 릴리스 노트는 소프트웨어의 한 버전에 딸려 나가는 문서로, 그 버전에서 무엇이 바뀌었는지, 그 변경이 누구에게 영향을 주는지, 그리고 독자가 해야 할 일이 있다면 무엇인지를 알린다. 릴리스마다 한 번 쓰고, 업그레이드할지 판단하는 사람, 자신이 겪은 문제가 고쳐졌는지 확인하는 사람, 제품을 지원하는 사람이 읽는다. 좋은 노트는 짧고, 그 버전에 한정되어 구체적이며, 무언가 깨지는 부분에 대해 솔직하다.

소프트웨어 릴리스 노트란 무엇인가

한 릴리스를 날짜와 버전과 함께 요약한 글이다. 릴리스 노트는 그 자리에 없었던 독자의 세 가지 질문에 답한다. 무엇이 달라졌는가, 나에게 영향이 있는가, 내가 조치해야 하는가. 프로젝트의 전체 이력은 체인지로그이고, 커밋 로그는 코드를 쓴 사람들을 위한 것이다.

같은 사실이 체인지로그 항목과 릴리스 노트에 모두 나올 수 있다. 차이는 선별과 독자에 있다. 체인지로그는 눈에 띄는 변경을 모두 나열하고, 릴리스 노트는 독자가 알아챌 변경을 앞세워 설명한다. 체인지로그 대 릴리스 노트가 그 경계를 자세히 그린다.

소프트웨어 릴리스 노트에는 무엇이 들어가야 하는가

버전과 날짜, 한 단락의 요약을 쓰고, 이어서 독자가 그것으로 무엇을 할 수 있는지에 따라 묶은 변경을 쓴다. 각 변경마다 독자의 말로 무엇이 달라졌는지, 누가 영향을 받는지, 조치가 필요한지를 밝힌다.

완전한 노트는 다음 요소로 이루어진다.

1. 버전 번호와 릴리스 날짜. 태그가 쓰는 형식을 그대로 써서, 독자가 노트를 빌드와 맞춰 볼 수 있게 한다.
2. 요약. 두세 문장으로, 이 릴리스가 무엇을 위한 것인지와 업그레이드에 독자의 작업이 필요한지를 쓴다.
3. 새 기능과 개선. 코드에 무엇이 들어갔는지가 아니라 독자가 이제 무엇을 할 수 있는지.
4. 수정. 사라진 증상과 그것이 시작된 버전.
5. 파괴적 변경과 지원 중단. 무엇이 동작하지 않게 되는지, 언제인지, 대신 무엇을 써야 하는지. 있다면 맨 앞에 둔다.
6. 알려진 문제. 출시했지만 올바르지 않다고 아는 모든 것과, 있다면 우회 방법.
7. 요구 사항과 업그레이드 단계. 지원 플랫폼, 최소 버전, 마이그레이션 명령.

리팩터링, 눈에 보이는 영향이 없는 의존성 업데이트, 내부 티켓은 빼라. 독자가 알아챌 수 없는 변경은 git 이력에 속한다. 표현과 순서는 릴리스 노트를 쓰는 방법이 다룬다.

소프트웨어 릴리스 노트는 어떤 모습인가

가상의 명령줄 도구를 위한 짧은 예시다. 내용보다 형태가 중요하다.

## 2.4.0 (2026-10-08)

Faster exports and one breaking change to the config file. Upgrade
needs a one-line edit to `tool.yml`.

### Breaking
- `output:` in `tool.yml` is now `export.path:`. Old configs fail
  with "unknown key". Rename the key; nothing else changes.

### New
- Exports stream to disk, so files over 100 MB no longer time out.

### Fixed
- Search works again for queries containing a hyphen. Broken
  since 2.3.0.

### Known issues
- Windows paths longer than 260 characters still fail. Use a
  shorter output directory for now.

파괴적 변경이 맨 앞에 있고 독자가 실제로 보게 될 오류 문구가 그대로 적혀 있다. 사람들은 오류 메시지로 검색하기 때문이다. 수정 항목은 그 버그가 생긴 버전을 밝혀서, 독자가 자신의 문제가 시작된 시점과 맞춰 볼 수 있다. 알려진 문제에는 우회 방법이 있는데, 침묵보다 낫다. 항목 종류별 표현은 릴리스 노트 예시에 더 있다.

독자별로 릴리스 노트는 어떻게 달라지는가

하나의 원본을 유지하고 독자마다 한 버전씩 써라. 사실은 바뀌지 않지만 상세한 정도는 바뀐다. 고객은 이점을 한 줄로 원하고, 관리자는 요구 사항과 알려진 문제를 원하고, 개발자는 정확한 이름과 버전을 원하며, 지원팀은 티켓이 들어왔을 때 무슨 말을 해야 하는지 알고 싶어 한다.

API 제품에서는 개발자용 버전에 가장 공을 들여야 한다. 여러분에게는 작은 수정인 변경이 호출자에게는 장애가 될 수 있기 때문이다. API 체인지로그와 파괴적 변경이 그 독자를 다룬다. 내부용 버전은 내부용 릴리스 노트가 고객에게는 필요 없고 지원과 영업에는 필요한 것이 무엇인지 설명한다.

소프트웨어 릴리스 노트는 어디에 게시해야 하는가

독자가 질문을 떠올리는 순간 이미 있는 곳에 게시하라. 모바일 앱이라면 스토어 목록이며, 플랫폼이 버전별 릴리스 노트 필드를 제공한다. Apple은 빌드의 릴리스 노트를 제공하는 방법을 문서화해 두었다. 웹 제품이라면 앱에서 링크된 체인지로그 페이지다. 라이브러리라면 릴리스 페이지와 저장소의 파일이며, GitHub 릴리스 노트에 설명된 대로다.

모든 버전을 고정된 URL에 두어 지원팀이 링크할 수 있게 하고, 예전 버전도 지우지 마라. 2.2 버전을 쓰는 독자는 2.3과 2.4의 노트도 필요하다. 시작할 구조가 필요하다면 릴리스 노트 템플릿에서 복사할 제목들을 얻을 수 있다.

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

변경이 필요로 하는 만큼이고 그보다 길지 않게. 패치 릴리스는 세 줄이면 된다. 마이그레이션이 있는 주요 릴리스는 한 페이지가 필요하고, 노트에서 링크하는 별도의 마이그레이션 가이드도 필요할 것이다. 기준은 첫 화면만 훑은 독자가 그 릴리스가 자신에게 영향을 주는지 아는가이다. 모른다면 요약을 위로 올리고 나머지를 줄여라. 무엇이 유효하고 무엇이 습관인지는 릴리스 노트 모범 사례가 정리한다.

FAQ

소프트웨어 릴리스 노트란 무엇인가? 소프트웨어의 한 릴리스에서 무엇이 바뀌었는지를 사용하거나 지원하는 사람을 위해 버전별로 요약한 글이다. 새 기능, 수정, 파괴적 변경, 그리고 독자가 해야 할 일을 다룬다.

릴리스 노트와 체인지로그는 무엇이 다른가? 체인지로그는 눈에 띄는 변경을 모두 담은 지속적인 기록이다. 릴리스 노트는 한 릴리스에 대한 메시지로, 업그레이드할지 판단하는 독자를 위해 골라서 다시 쓴 것이다. 많은 팀이 한 버전의 체인지로그 항목을 그 버전의 릴리스 노트로 게시한다.

소프트웨어 릴리스 노트는 누가 쓰는가? 보통 프로덕트 매니저, 테크니컬 라이터, 또는 그 변경을 출시한 엔지니어가 쓰고, 어조는 다른 사람이 검토한다. 변경에 가장 가까운 사람이 초안을 쓰고 두 번째 사람이 독자 관점에서 다듬을 때 결과가 가장 좋다.

마이너 릴리스에도 릴리스 노트가 필요한가? 필요하다. 짧게라도 쓴다. 패치 릴리스도 무엇을 고쳤는지, 독자가 조치해야 하는지는 말해야 한다. 한 줄짜리 노트가 없는 것보다 낫다. “버그 수정 및 개선”은 독자에게 아무것도 알려 주지 않기 때문이다.

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

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