체인지로그

제품은 매주 바뀌는데 바뀌었다는 사실은 아무 데도 남지 않던 시절이 있었습니다. 만든 사람 머릿속에만 있으니 한 달만 지나도 "그 버튼 원래 저기 있었나" 를 아무도 확정하지 못했습니다. 바뀐 것을 확인하려면 코드 저장소에 쌓인 변경 기록을 한 줄씩 거슬러 올라가야 했는데, 그 기록은 개발자가 자기 작업 단위로 남긴 메모라서 "인증 토큰 만료 처리 수정" 같은 문장이 수백 개 이어질 뿐이었습니다.

그래서 고객 문의가 들어올 때마다 같은 장면이 반복됐습니다. 페이지덱에서 고객이 "어제까지 되던 내보내기가 오늘 안 된다" 고 알려 오면 수아가 태오에게 묻고, 태오는 최근 배포 목록을 뒤져 짚이는 변경을 찾아봅니다. 답이 오는 데 반나절이 걸리고, 그동안 수아는 고객에게 확인 중이라는 말만 되풀이합니다. 바뀐 게 맞는지조차 모르니 사과할지 설명할지도 정하지 못합니다.

체인지로그는 이 확인 비용을 없애려고 만든 목록입니다. 배포할 때마다 무엇이 바뀌었는지를 사람이 읽을 수 있는 한 줄로 남겨 두면, 다음에 같은 질문이 왔을 때 목록만 열어 날짜를 짚으면 됩니다. 기억이나 추적이 아니라 기록이 답하게 만든 겁니다.

한 항목은 판 번호 또는 날짜, 변경의 성격을 나타내는 분류, 무엇이 어떻게 달라졌는지 적은 한 줄로 이뤄집니다. 최신 항목이 맨 위에 오고 아래로 갈수록 과거가 됩니다.

1. 판 이름과 날짜. 2.4.0 — 2026-09-16 처럼 적습니다. 판 번호를 붙일 때는 시맨틱 버저닝을 많이 씁니다. 세 자리 숫자로 변경의 크기를 표시하는 규칙인데, 앞자리가 오르면 기존 사용 방식이 깨지는 변경이고 가운뎃자리는 기능 추가, 뒷자리는 버그 수정입니다.
2. 변경 분류. 추가·변경·수정·삭제·지원 종료·보안 여섯 가지로 나누는 방식이 흔합니다. 한 배포에 열 건이 섞여 있어도 독자는 자기에게 필요한 분류만 훑고 지나갈 수 있습니다.
3. 변경 내용 한 줄. "문서 목록에서 태그로 거르는 기능을 추가했습니다" 처럼 사용자가 겪는 말로 적습니다. "TagFilterService 를 도입했습니다" 는 안쪽 구현이라 읽는 사람에게 아무것도 알려 주지 않습니다.
4. 영향 범위. 기존 동작이 깨지는 변경이라면 그 사실을 항목 안에 표시합니다. 이렇게 남의 코드를 깨뜨리는 변경을 브레이킹 체인지라고 부르고, 이때는 무엇을 대신 써야 하는지도 같은 줄에 적습니다.
5. 참고 링크. 그 변경을 자세히 설명한 문서나 이슈 번호를 답니다. 한 줄로 부족한 독자만 따라 들어가면 되니 본문은 짧게 유지됩니다.

항목을 쌓는 단위는 배포지 작업이 아닙니다. 기능 하나를 만드는 데 변경 열두 건이 들었어도 사용자가 겪는 달라짐이 하나라면 한 줄로 적습니다. 반대로 한 번에 나간 변경이라도 겪는 쪽이 다르면 줄을 나눕니다. 화면에 버튼이 생긴 것과 그 기능의 응답 형식이 달라진 것은 읽는 사람이 다르기 때문입니다.

쓰는 사람은 그 변경을 만든 사람입니다. 배포가 끝난 뒤 한 명이 몰아서 정리하면 기억이 흐려진 채로 적히고, 결국 커밋 메시지를 그대로 옮겨 붙이게 됩니다. 페이지덱은 변경을 합칠 때 한 줄을 함께 적어 두고 배포 시점에 그 줄들을 모으는 방식으로 씁니다.

읽는 사람은 둘로 갈립니다. 안쪽에는 고객 문의를 받는 수아, 무엇이 바뀌었는지 확인하고 시험하는 태오, 이번 달에 나간 것을 정리해 고객사에 보고하는 사람이 있습니다. 바깥쪽에는 이 제품을 프로그램으로 연결해 쓰는 개발자가 있습니다. 다른 프로그램이 호출해 쓰라고 열어 둔 창구를 API라고 하는데, 이 창구의 규격이 바뀌면 연결해 둔 쪽 코드가 멈춥니다. 그래서 API 를 제공하는 제품에서는 체인지로그가 공개 문서로 운영됩니다.

두 독자의 요구는 방향이 다릅니다. 안쪽은 빠짐없이 다 적힌 것을 원하고, 바깥쪽은 자기 연결이 깨지는지만 알고 싶어 합니다. 그래서 내부용 전체 목록을 먼저 쌓고 그중 외부에 영향 있는 항목만 공개 목록으로 추리는 팀이 많습니다. 목록을 둘로 나눌 여력이 없다면 하나만 두되 외부 영향 여부를 항목마다 표시해 둡니다.

"이거 언제부터 이렇게 바뀐 거예요? 체인지로그 확인해 볼게요."

기억에 기대지 말고 기록에서 날짜를 짚어 보자는 뜻입니다.

"그 변경 체인지로그에 안 올라갔는데요."

배포는 됐는데 기록이 빠졌다는 지적입니다. 기록 없이 나간 변경은 문의가 들어왔을 때 원인을 찾을 수 없습니다.

"다음 판에서 옛 방식 지원을 끊으니까 체인지로그에 미리 올려 주세요."

바뀌기 전에 예고하는 자리로도 쓴다는 말입니다.

페이지덱에서는 릴리스 직전에 지현이 이번에 나가는 항목을 한 번 훑습니다. 태오가 쌓아 둔 줄 가운데 사용자 말로 다시 써야 할 것을 고치고, 기존 동작이 달라지는 항목이 있으면 수아에게 먼저 알립니다. 수아는 그 항목을 보고 해당 기능을 자주 쓰던 고객사에 미리 연락합니다.

문의가 들어왔을 때 열어 보는 순서도 정해져 있습니다. 수아가 날짜를 짚어 그날 나간 항목을 확인하고, 짚이는 변경이 있으면 그 줄에 달린 링크를 따라 자세한 내용을 봅니다. 없으면 그제서야 태오에게 묻습니다. 반나절 걸리던 확인이 몇 분으로 줄어드는 자리가 여기입니다.

체인지로그를 사용자에게 보여 주는 홍보 글로 여기는 경우가 가장 많습니다. 바깥에 공개하는 문서니 잘 보이게 써야 한다는 생각이 자연스럽게 따라붙습니다. 그런데 이 목록의 쓸모는 빠짐없이 적혀 있다는 데서 나옵니다. 자랑할 만한 기능만 골라 적고 조용히 끊은 기능이나 동작이 달라진 부분을 빼면, 정작 문제가 생겼을 때 목록을 열어 본 사람이 원인을 못 찾습니다. 그러면 다음부터는 아무도 이 목록을 열지 않습니다.

미루어 두었다가 한꺼번에 정리하면 된다고 보는 것도 흔합니다. 변경 하나하나가 작아 보여서 나중에 모아 쓰는 게 효율적으로 느껴집니다. 하지만 두 주가 지나면 왜 그렇게 바꿨는지가 빠지고 결과만 남습니다. 결국 목록은 "성능을 개선했습니다" 같은 줄로 채워지고, 그런 줄은 어떤 질문에도 답하지 못합니다. 쌓는 비용은 변경 시점에 한 줄이지만 되살리는 비용은 훨씬 큽니다.