체인지로그란 무엇이고, 무엇이 들어가야 하는가

체인지로그란 제품에서 무엇이 바뀌었는지를 날짜순으로 기록한 것으로, 이를 출시한 팀이 아니라 그 변경으로 영향을 받는 사람들을 위해 작성된다. 각 항목은 하나의 변경 사항을 명명하고, 언제 발효되었는지 말하며, 독자가 그것에 대해 무엇을 해야 하는지 말한다. 대부분의 항목에서 그것은 아무것도 하지 않아도 된다는 뜻이다. 바로 이 마지막 부분이 체인지로그를 커밋 로그와 구분한다. 커밋 로그는 코드를 작성한 사람들을 위한 기록이고, 체인지로그는 그것을 사용하는 사람들을 위한 기록이다.

체인지로그란 정확히 무엇인가

날짜가 적힌 항목들의 목록으로, 최신순으로 나열되며, 각각은 독자가 확인할 수 있는 용어로 하나의 변경 사항을 설명한다. 팀이 무엇을 만들었는지가 아니라 지금 무엇이 달라졌는지다. “결제 서비스 리팩터링”은 커밋 메시지다. “청구서가 이제 세금을 별도 항목으로 표시한다”는 체인지로그 항목이다. 독자가 자신의 계정에서 확인할 수 있는 무언가를 말해주기 때문이다.

이 형식은 오래되었고 의도적으로 단순하다. 릴리스나 날짜마다 제목 하나, 그 아래 짧은 목록, 때로는 카테고리 레이블이 붙는다. Keep a Changelog는 이 형식에서 가장 많이 인용되는 명세이며, 존재하는 이유는 명세를 건너뛴 대부분의 프로젝트가 결국 커밋 히스토리를 그대로 쏟아내는 것으로 끝나기 때문인데, 이는 독자가 가지고 온 질문과는 다른 질문에 답하는 것이다.

이 다섯 가지는 실제로는 겹치지만 같은 문서가 아니며, 차이는 읽는 순간 누가 그것을 손에 들고 있는가에 있다. 체인지로그는 나중에 검색되고 다시 링크되도록 만들어진 것이어서, 그 항목들은 다른 것들보다 안정적인 날짜와 URL을 더 필요로 한다.

체인지로그 항목에는 실제로 무엇이 들어가는가

네 가지, 이 순서대로다. 무엇이 바뀌었는지, 사용자나 호출자가 알아챌 용어로 표현된 것. 언제 발효되었는지. 어느 카테고리에 속하는지(added, fixed, changed, removed가 흔한 네 가지다). 그리고 중요할 때는 독자가 그것에 대해 무엇을 해야 하는지. 더 자세한 내용으로의 링크는 환영받는다. 내부적인 정당화 문단은 그렇지 않다. 독자는 왜냐고 묻지 않았고, 무엇이냐고 물었기 때문이다.

## 2026-09-07

### Added
- 청구서가 이제 고객 계정 통화로 세금을 별도 항목으로 표시한다.

### Fixed
- 보고서를 CSV로 내보낼 때 보고서가 10,000행을 넘어도 더 이상
  마지막 행을 잃지 않는다.

이 형식은 구조를 바꾸지 않고도 두 줄짜리 업데이트부터 한 릴리스에 수록된 백 개의 항목까지 확장된다. 이것이 어떤 형식이 실제로 작동하는지에 대한 진짜 테스트다. 바쁜 주에도 조용한 주에도 똑같이 읽히는가.

누가 체인지로그를 쓰고, 언제 쓰는가

변경을 실제로 만든 사람이, 출시되는 순간에 쓴다. 일주일 후 티켓에서 재구성하는 기술 작가가 아니다. 코드를 만진 사람은 사용자에게 실제로 무엇이 바뀌었는지 안다. 나중에 쓰인 요약은 실제로 출시된 것보다 티켓을 설명하는 경향이 있으며, 이는 대체로 실제 범위보다 넓거나 좁다. 일부 팀은 항목이 공개되기 전에 검토 단계를 추가하는데, 주로 스며든 내부 언어를 잡아내기 위해서이며, 그 검토는 항목이 같은 날 나갈 만큼 충분히 빨라야 한다.

체인지로그는 어디에 있어야 하는가

안정적인 URL을 가진 자체 페이지에, 피드로 배포된다. 설정 메뉴나 코드 호스트의 릴리스 태그에 파묻혀 있으면 어디를 봐야 하는지 이미 알고 있던 사람들에게만 닿는다. 공개 페이지는 지원 티켓에서 링크되고, 리뷰에서 인용되고, 구독될 수 있다. 피드는 페이지만큼 중요하다. 제품의 체인지로그를 한 달에 한 번 확인하는 독자는 드물고, 구독하는 독자는 그렇지 않으며, 오직 피드만이 후자를 위한다.

릴리스 노트와는 어떻게 다른가

이 둘은 끊임없이 혼동되며, 섞으면 어느 쪽 독자도 제대로 만족시키지 못하는 문서가 나올 만큼 다르다. 체인지로그 대 릴리스 노트가 이 차이를 완전히 다룬다. 짧게 말하면, 체인지로그는 완전하고 시간순인 기록이고, 릴리스 노트는 업데이트가 가질 가치가 있는 것처럼 들리도록 쓰인 선별된 부분집합이다. 제품은 보통 둘 다 필요하며, 독자의 하루 중 서로 다른 순간을 겨냥한다.

무엇이 체인지로그를 읽을 가치가 있게 만드는가

자기 범위에 대한 구체성과 정직함이다. “다양한 버그 수정”은 독자에게 페이지를 그만 열게 만드는 문장이다. 확인할 수 있는 것을 아무것도 약속하지 않기 때문이다. 작은 수정이라도 정확히 바뀐 동작을 명명한 항목이 구독을 살아있게 만드는 항목이다. 이 원칙은 생략하는 것에도 적용된다. 성공만 발표하고 고장 난 것에 대한 수정은 절대 발표하지 않는 체인지로그는 체인지로그 옷을 입은 마케팅처럼 읽히며, 독자는 그것을 알아챈다.

버전 관리 원칙도 중요하다. 시맨틱 버저닝과 당신의 체인지로그는 버전 번호와 항목이 어떻게 일치해야 하는지 보여준다. 버전 히스토리를 훑어보는 독자가 두 개의 다른 신호가 아니라 같은 신호를 두 번 받도록 하기 위해서다.

체인지로그는 어떻게 생성되는가

두 가지 방식이 있고, 대부분의 실제 설정은 둘의 혼합이다. 자동 생성은 커밋 메시지를 읽는데, 보통 Conventional Commits 형식이며, 아무도 결과물을 건드리지 않고 항목으로 바꾼다. Conventional Commits에서 체인지로그로가 그 파이프라인을 다룬다. 선별 생성은 누군가가 각 항목을 손으로 쓰거나 편집한다는 뜻이다. 자동화된 결과물은 더 빠르고 병합된 풀 리퀘스트를 절대 놓치지 않지만, 모호한 커밋 메시지를 그대로 물려받는다. 그래서 자동화하는 대부분의 팀도 원본 결과물을 그대로 보여주기보다는 게시 전에 가벼운 편집 단계를 유지한다.

FAQ

모든 제품에 체인지로그가 필요한가? 변경으로 영향을 받는 사용자가 있는 제품이라면, SaaS 앱이든 내부 도구든 공개 API든 필요하다. 형식은 적응하지만(API 체인지로그는 소비자 앱과는 다르게 읽힌다) 필요성은 그렇지 않다.

소프트웨어 용어로 체인지로그란 무엇인가? 위와 같은 정의다. 소프트웨어에서 무엇이 바뀌었는지에 대한, 날짜가 적힌 시간순 목록으로, 그것을 만든 사람이 아니라 사용하는 사람을 위해 작성된다.

체인지로그는 커밋에서 자동으로 생성될 수 있는가? 그렇다. 많은 팀이 정확히 그렇게 하며, 보통 Conventional Commits 형식의 메시지에서 생성한다. 절충안은 생성된 항목이 그 출처인 커밋 메시지만큼만 명확하다는 것이어서, 게시 전 검토 과정이 재구성이 필요한 항목을 잡아낸다.

체인지로그는 버전 히스토리와 같은 것인가? 용어가 서로 바꿔 쓰일 만큼 가깝다. 버전 히스토리는 때로 설명 없이 버전 번호와 날짜만 나열한 목록에 불과하다. 체인지로그는 항상 무엇이 바뀌었는지를 포함한다.

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

changeloop 관련 페이지: changelog 예시, 개발자 문서