Git 태그, 릴리스, 그리고 당신의 체인지로그

Git 태그, 릴리스, 체인지로그 항목은 같은 사건에 대한 세 가지 다른 기록이며, 이것들을 혼동하면 체인지로그가 실제로 출시된 것에서 조용히 멀어지게 된다. 태그는 커밋을 표시한다. 릴리스는 그 태그를 아티팩트와 설명으로 패키징한다. 체인지로그 항목은 저장소 밖의 독자가 사용할 수 있는 용어로 무엇이 바뀌었는지 설명한다. 보통 시간적으로 가깝게 일어나며, 바로 그렇기 때문에 셋을 하나의 단계로 취급하기 쉽고, 바로 그렇기 때문에 그 격차는 누군가 “v2.4에 뭐가 출시됐지”라고 묻고 정직한 답이 진짜 발굴을 필요로 할 때에야 몇 달 후에 비로소 눈에 보이게 된다.

셋 사이의 실제 차이는 무엇인가

태그는 셋 중 가장 기계적이다. git tag v2.4.0 하면 끝이고, 무언가가 그 안에 무엇이 있는지 설명해야 한다는 요구사항이 전혀 없다. 릴리스는 설명과 보통 다운로드 가능한 아티팩트를 추가하며, 그 대상은 여전히 릴리스 페이지가 무엇인지 아는 개발자들이다. 체인지로그 항목은 셋 중 유일하게 저장소를 절대 열지 않을 수도 있는 독자를 위해 작성되며, 그래서 가장 많은 편집상의 주의가 필요하고 마감 압박 속에서 가장 건너뛰기 쉬운 것이다.

모든 git 태그에 체인지로그 항목이 필요한가

아니다, 그리고 둘을 1대1로 취급하는 것은 흔한 실수다. 태그는 내부 마일스톤, 릴리스 후보, 또는 대부분의 사용자에게 절대 도달하지 않는 핫픽스를 표시할 수 있다. 이 중 어느 것도 반드시 공개 항목이 필요한 것은 아니다. 테스트는 애초에 무언가가 체인지로그에 속하는지 결정하는 것과 같다. 사용자나 호출자가 그것을 알아차리거나 신경 쓸 것인가. 대부분의 태그는 이 테스트를 통과한다. CI 파이프라인을 트리거하기 위해서만 만들어진 태그처럼 일부는 절대 통과하지 못한다.

모든 체인지로그 항목에 자체 태그가 필요한가

항상 그런 것은 아니며, 여기서 지속적으로 배포하는 팀과 버전이 매겨진 패키지를 출시하는 팀이 갈린다. 하루에 여러 번 배포하는 SaaS 제품은 배포당 1대1 태그 없이 여러 배포를 하나의 날짜가 적힌 체인지로그 항목 아래 묶을 수 있다. 패키지 레지스트리에 게시되는 라이브러리는 보통 게시된 버전마다 태그가 필요하다. Go 모듈과 Swift Package Manager는 태그 자체로부터 버전을 해석한다. npm이나 PyPI에서는 레지스트리가 게시된 버전을 보관하며, 태그는 누구든 그 버전을 소스와 다시 연결하는 수단이다. 독립적으로 버전이 매겨지는 여러 패키지를 가진 저장소는 이것을 저장소 전체를 위해 한 번이 아니라 패키지 단위로 결정해야 하며, 모노레포 체인지로그가 태그 접두사와 체인지로그 범위가 폴더 경계가 아니라 패키지 경계를 따라야 하는 이유를 다룬다. 시맨틱 버저닝과 당신의 체인지로그가 버전 번호 자체가 체인지로그 카테고리에 어떻게 매핑되어야 하는지를 다룬다. 태그는 버전 번호를 실제 코드에 대해 검증 가능하게 만드는 메커니즘이다.

릴리스 설명은 체인지로그 항목과 어떻게 관련되어야 하는가

같은 텍스트일 수 있지만, 그것은 오직 둘의 대상이 진짜로 같을 때뿐이며, 이는 보이는 것보다 드물다. 코드 호스트의 릴리스 페이지는 거의 전적으로 개발자만 읽는다. 제품에 체인지로그를 읽는 비기술직 사용자도 있다면, 릴리스 설명을 그대로 복제하는 것은 평이한 언어 버전이 필요했던 독자에게 내부 용어와 코드 중심 표현을 보내는 것이다. 가장 깔끔한 패턴은 체인지로그 항목을 주요한, 독자 지향적인 아티팩트로 작성하고, 릴리스 설명은 거기로 링크하거나 이미 그곳에 익숙한 대상을 위해 더 짧고 더 기술적인 요약을 유지하도록 두는 것이다.

# 릴리스 v2.4.0 (GitHub, 개발자용)
보고서 파이프라인을 새 집계 엔진으로 업그레이드. 고객 지향 요약은
체인지로그 참조: https://example.com/changelog#v2.4.0

## 2026-09-07 (체인지로그, 고객 지향)
### Added
- 이제 보고서가 백만 행이 넘는 계정에서도 1초 이내에 로드된다.

같은 릴리스, 두 개의 문서, 각각 자신의 독자를 위한 자신의 표현으로.

체인지로그 항목은 실제로 어디서 오는가

두 가지 출발점에서, 그리고 대부분의 실제 파이프라인은 둘의 혼합이다. 태그 시점에 커밋 메시지에서 생성될 수 있으며, 이는 빠르고 병합된 풀 리퀘스트를 절대 놓치지 않는다. Conventional Commits에서 체인지로그로가 그 파이프라인을 완전히 다룬다. 또는 태그와 완전히 별개로 손으로 작성될 수 있으며, 코드가 병합되는 순간이 아니라 기능이 완료되었다고 간주되는 순간에 맞춰진다. 생성된 항목은 일관되지만 모호한 커밋 메시지를 그대로 물려받는다. 손으로 작성된 항목은 더 명확하지만 실제로 그것을 쓸 누군가가 필요하다. 자동화하는 대부분의 팀도 원본 결과물을 그대로 보여주는 대신, 그것이 공개 항목이 되기 전에 생성된 텍스트에 가벼운 편집 단계를 유지한다. Keep a Changelog, 실전편이 권장하는 것과 같은 원칙이며, 원본 텍스트가 애초에 어디서 왔는지와 상관없이 그렇다.

셋이 동기화에서 벗어나면 무엇이 깨지는가

독자가 먼저 확인한 것에 대한 신뢰다. 대응하는 체인지로그 항목 없이 존재하는 태그는 체인지로그 독자 쪽에서 보면 그 주에 아무 일도 없었던 것처럼 보인다. 대응하는 태그나 릴리스가 없는 체인지로그 항목은 프로덕션 문제를 디버깅하는 누군가가 항목이 게시되었을 때 라이브였던 정확한 코드를 체크아웃하는 것을 불가능하게 만든다. 해법은 완벽한 자동화가 아니라 그 대응 관계에 대한 단일한 진실의 원천이다. 릴리스 프로세스 자체의 체크리스트일 뿐이라도, 출시 가능한 변경이 그것을 도입하는 같은 커밋이나 풀 리퀘스트에서 셋 모두를 받는다고 말하는 한 장소.

FAQ

체인지로그 항목은 git 태그에서 자동으로 생성되어야 하는가? 출발점이 될 수는 있지만, 태그 하나만으로는 독자 지향적인 설명을 전혀 담지 못한다, 커밋 범위만 담을 뿐이다. 자동화된 생성은 사용 가능한 무언가를 만들어내려면 태그의 존재뿐만 아니라 그 범위 안의 커밋 메시지를 읽어야 한다.

모든 릴리스에 태그를 달지 않으면 어떻게 되는가? 그러면 체인지로그 항목이 주요 기록이 되며, 그래도 날짜와, 제품에 버전이 있다면 버전 번호를 담아야 한다, 대응하는 태그가 없어도 항목이 나중에 독자가 참조할 수 있는 것으로 남도록.

사전 릴리스 태그(v2.4.0-rc.1 같은)도 체인지로그 항목을 가져야 하는가? 일반적으로는 아니다. 릴리스 후보는 내부 또는 베타 테스트용이며, 그것을 위한 체인지로그 항목은 독자에게 설명된 그대로 절대 출시되지 않을 수도 있는 버전에 대한 항목을 기대하도록 훈련시킨다. 항목은 일반 공급에 도달하는 태그를 위해 남겨두라.

하나의 체인지로그 항목이 여러 git 태그를 다룰 수 있는가? 그렇다, 그리고 자주 태그를 다는 팀에게는 종종 그래야 한다. 기능을 여러 읽기에 걸쳐 조각내는 태그당 얇은 항목을 게시하는 대신, 관련된 태그를 순 변경 사항을 설명하는 하나의 날짜가 적힌 항목 아래로 묶으라.

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

changeloop 관련 페이지: changelog 생성기, 개발자 문서