체인지로그 대 릴리스 노트: 무엇이 다른가?

체인지로그는 무언가를 찾아보려는 사람을 위해 쓰인, 바뀐 모든 것을 계속 누적해 나가는 기록이다. 릴리스 노트는 이 릴리스가 자신에게 중요한지 판단하려는 사람을 위해 쓰인, 하나의 릴리스에 대한 선별된 메시지다. 그 차이는 서식이 아니라 독자에게 있으며, 대부분의 팀은 둘 다 필요하다. 하나는 참고 자료로, 하나는 발표문으로, 같은 항목들에서 파생된 형태로.

대부분의 팀은 우연히 둘 중 하나를 갖게 되고, 요청에 의해 나머지 하나를 갖게 된다. 처음에는 어떤 개발자가 무엇이 출시되었는지 기록을 원해서 체인지로그로 시작한다. 몇 달 후 지원팀의 누군가가, 4월부터 이미 살아 있던 기능을 고객들이 왜 몰랐는지 묻고, 그제서야 릴리스 노트가 필요해진다.

체인지로그 대 릴리스 노트, 나란히 놓고 비교하기

체인지로그란 무엇인가

체인지로그는 최신순으로 정렬되고, 각 항목이 유형(added, changed, deprecated, removed, fixed, security)과 날짜로 표시된, 무엇이 바뀌었는지에 대한 시간순의 거의 완전한 기록이다. 그 독자는 이미 관심을 갖기로 결정한 상태다. 그들은 무언가를 찾고 있다. 어떤 동작이 언제 바뀌었는지, 버그가 고쳐졌는지, 어떤 버전에서 플래그가 도입되었는지. 완전성이 그 모든 가치이며, 그것이 Keep a Changelog 관례가 단 한 페이지의 대부분을 구조에 쓰고 산문에는 거의 쓰지 않는 이유다.

릴리스 노트란 무엇인가

릴리스 노트는 하나의 릴리스에 대해 산문으로 쓰인, 선별적인 메시지다. 그 독자는 아직 아무것도 결정하지 않았다. 그들은 이 릴리스가 자신에게 중요한지, 그리고 그것에 대해 무엇을 해야 하는지를 판단하는 중이다. 선별이 그 모든 가치다. 모든 것을 나열하는 릴리스 노트는 문단으로 이루어진 체인지로그일 뿐이며, 무언가를 빼먹은 체인지로그가 독자를 실망시키는 것과 같은 방식으로 독자를 실망시킨다. 릴리스 노트를 쓰는 방법은 그 선별과 문구에 관한 글이다.

체인지로그와 릴리스 노트가 둘 다 필요한가

두 독자층이 서로 다른 것을 원하기 시작하면 둘 다 필요하다. 그 전까지는 하나의 성과물이 두 역할을 모두 하는 것이 맞다. 작은 팀들은 각 항목 맨 위에 짧은 문단을 붙인 단일 /changelog 페이지를 발행하며, 한동안은 그것이 수정 사항을 찾는 개발자와 소식을 훑어보는 고객 모두에게 똑같이 잘 작동한다. 너무 일찍 나누면 유지 관리해야 할 것이 두 개로 늘어나고, 그중 하나는 썩어간다.

다음과 같은 일이 벌어지기 시작하면 나눌 가치가 생긴다.

• 체인지로그 항목에 개발자들이 그냥 지나쳐버리는 설명 문단이 늘어난다.
• 혹은 반대로, 릴리스 발표문에 의존성 업데이트가 나열되기 시작한다.
• 지원팀이 항목들을 이메일에 복사해 넣고 그 과정에서 다시 쓰고 있다.
• 누군가 “파괴적 변경만” 요청하는데 그것만 걸러낼 수가 없다.

마지막 항목이 진짜 신호다. “나에게 영향을 미치는 것이 무엇인지”에 모든 것을 읽지 않고는 아무도 답할 수 없다면, 하나의 성과물이 두 역할을 서투르게 하고 있는 것이다.

하나의 원천, 두 가지 뷰

흔한 실수는 이 둘을 두 개의 문서로 취급하는 것이다. 이것들은 같은 변경 사항 집합에 대한 두 가지 뷰다.

체인지로그는 진행하면서 작성하라. 의미 있는 변경마다 하나의 항목을, 각각 fixed, added, changed, removed, deprecated, security 중 무엇인지 태그를 붙여서. 항목을 짧게 유지해서 그것을 쓰는 일 자체가 하나의 결정이 되지 않도록 하라. 그러고 나서 릴리스 시점에 릴리스 노트는 선별이자 다시 쓰기가 된다. 사람에게 중요한 항목들을 골라, 그것이 누군가로 하여금 할 수 있게 해주는 일에 따라 묶고, 이유를 맨 위에 둔다.

여기에는 실용적인 결과가 하나 따라온다. 체인지로그가 원천이라면, 그것은 손으로 관리하는 페이지가 아니라 구조화된 데이터여야 한다. 항목은 유형, 날짜, 버전, 그리고 누구를 위한 것인지 말하는 방법을 가져야 한다. 그것이 갖춰지면 공개 페이지, 앱 내부 위젯, RSS 또는 JSON 피드는 하나의 것에 대한 세 가지 렌더링이 되고, 고객에게 가는 길에 아무도 아무것도 다시 쓰지 않는다. 릴리스 노트 이메일도 이메일을 보내는 도구가 무엇이든 거기서 같은 항목을 인용할 수 있다. 체인지로그 자동화는 이 단계들 중 어느 것을 기계가 맡아야 하는지에 관한 글이다. 그것이 체인지로그를 페이지가 아니라 피드로 다루어야 한다는 논거의 전부다. 그리고 솔직히 말해 그것이 바로 우리가 만들고 있는 것이기도 하니, 이 글은 중립적인 조사가 아니라 이해관계가 있는 입장으로 읽어주기 바란다.

시간이 하나만 있다면

체인지로그를 써라. 항목당 비용이 더 낮고, 쓰는 그 날부터 유용하며, 릴리스 노트는 나중에 그것으로부터 도출할 수 있다. 그 반대는 성립하지 않는다. 열두 통의 발표 이메일로부터 일 년치 변경 사항을 재구성할 수는 없으며, 사람들은 그것을 요구할 것이다.

도출이 계속 가능하도록 고정된 형식으로 유지하라. 우리의 체인지로그 예시 페이지는 이것을 잘 해내는 팀들의 항목을 모아 놓았고, 릴리스 노트 템플릿은 우리가 항목들의 집합을 보낼 가치가 있는 무언가로 바꿀 때 사용하는 형식이다.

이름 짓기에 대한 한마디

이것은 표준화되어 있지 않으며, “release notes”가 계속 이어지는 목록을 가리키는 데 쓰이고 “changelog”가 분기별 발표를 가리키는 데 쓰이는 경우도 발견하게 될 것이다. 단어를 두고 논쟁할 가치는 없다. 여러분의 각 성과물이 두 역할 중 어느 것을 하고 있는지 정하고, 팀에서 이미 부르는 대로 이름을 붙이고, 어느 쪽도 조용히 둘 다 하고 있지는 않은지 확인하라.

결과가 어느 표면에 안착할지는 별도의 결정이며, 체인지로그 페이지 만드는 법에서 다룬다.

FAQ

체인지로그와 릴리스 노트는 같은 것인가? 아니다. 체인지로그는 무언가를 찾아보려는 사람들이 읽는 완전한 기록이고, 릴리스 노트는 관심을 가질지 판단하려는 사람들이 읽는 선별된 발표문이다. 같은 변경 사항이 둘 다에 등장하지만, 각 독자에 맞게 다르게 표현된다.

릴리스 노트를 체인지로그로부터 생성할 수 있는가? 그렇다. 그것이 옳은 방향이다. 사람이 관심을 가질 항목들을 선별하고, 결과별로 묶고, 헤드라인을 다시 써라. 반대 방향, 즉 발표문으로부터 체인지로그를 재구성하는 것은 발표문이 빼먹은 모든 것을 잃어버린다.

체인지로그는 어디에 있어야 하는가? 저장소 없이도 독자가 닿을 수 있는, 영구적이고 링크 가능한 곳. /changelog 페이지, 문서 사이트, 또는 여러 곳에서 렌더링되는 피드. CHANGELOG.md 하나만으로는 기여자에게는 닿지만 고객에게는 닿지 않는다.

체인지로그에 내부 변경 사항을 포함해야 하는가? 그렇다. 맨 아래에 한 줄씩. 체인지로그는 완전한 기록이다. 릴리스 노트에도 짧은 마지막 섹션으로 남겨둘 수 있다. 단, 독자가 알아챌 변경 사항이 먼저 와야 한다.

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

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