체인지로그 자동화, 그리고 그 한계에 대하여

체인지로그 자동화는 수집, 분류, 발행을 자동화하고 선별과 문구에서 멈출 때 작동한다. 모든 것을 자동화하면 포맷된 git log를 내보내게 되고, 아무것도 자동화하지 않으면 체인지로그는 릴리스 직전에 기억을 되짚어가며 몰아서 쓰게 된다. 유용한 질문은 어느 부분을 자동화할 것인가이지, 얼마나 자동화할 것인가가 아니다.

체인지로그 자동화 프로젝트는 두 방향 중 하나로 실패하며, 둘 다 첫 설계 회의에서부터 예측 가능하다. 너무 적게 자동화하면 체인지로그는 누군가 업데이트해야 할 문서가 되고, 그것은 곧 제비뽑기에서 진 사람이 몰아서 업데이트한다는 뜻이다. 너무 많이 자동화하면 포맷된 git log가 된다. 완전하고, 정확하지만, 아무도 읽지 않는다.

체인지로그의 어느 부분을 자동화해야 하는가

네 단계 중 세 단계다. 수집과 발행은 완전히, 분류는 사람의 재량 개입이 있는 첫 번째 통과로, 선별과 문구는 결코 자동화하지 않는다.

수집. 변경 사항이 일어나는 곳(커밋, PR, 티켓)에서 그것을 꺼내 목록으로 만드는 것. 이것은 완전히 자동화하라. 사람은 이 일에 서투르고, 지루하며, 마감 아래서 빼먹기 쉬운 단계다. Conventional commits나 PR 라벨이 보통의 원재료다.

분류. 무언가가 Added, Fixed, Changed, Deprecated, Removed, Security 중 무엇인지 결정하는 것. 커밋 유형이나 PR 라벨로부터 첫 번째 통과를 자동화하고, 사람이 재량으로 뒤집을 수 있게 하라. 메타데이터만으로도 정확도는 약 80퍼센트이며, 틀린 20퍼센트는 정확히 중요한 항목들에 몰려 있다. 모호함이 중요도와 상관관계를 갖기 때문이다.

선별과 문구. 독자에게 무엇을 알려야 하고 어떻게 말해야 하는지를 결정하는 것. 이것은 자동화하지 마라. 이것이 이 성과물의 가치 전부다. 나머지 모든 것은 물류에 불과하다.

발행. 완성된 항목들을 페이지, 피드, 이메일, 앱 내부 위젯, Slack 채널로 전달하는 것. 완전히, 하나의 원천으로부터 자동화하라. 실제로 수작업 노력 대부분이 들어가는 곳이 여기이며, 그것을 세는 사람은 거의 없다. 이것은 또한 변경을 요청한 사람에게 그것이 출시되었다고 알려줄 수 있는 단계이기도 하며, 그것이 체인지로그 쪽에서 피드백 루프를 닫는 일의 전부다. 그 단계의 이메일 절반은 제품 업데이트 이메일 템플릿에서 자체적인 형태를 갖는다.

마지막 요점은 곱씹어볼 가치가 있다. 팀들은 체인지로그를 글쓰기 문제로 여기는 경향이 있고, 그러고 나서 대부분의 시간을 배포에 쓴다. 항목을 이메일 도구에 복사하고, 앱 내부용으로 다시 포맷하고, Slack에 붙여넣고, 문서 페이지를 업데이트하는 것. 글쓰기는 한 시간이다. 복사는 릴리스마다 한 시간씩, 영원히 계속되며, 그것이 바로 기계가 맡아야 할 부분이다.

경계선이 옮겨지면 무슨 일이 일어나는가

위로 옮기면 git 덤프가 된다. 커밋으로부터의 완전한 자동화는 고객 앞에 bump deps, fix flaky test, wip, address review comments를 내놓게 된다. 이렇게 해본 모든 팀은 결국 필터를 추가했고, 그 필터는 다른 이름 아래 다시 도입된 선별 단계일 뿐이며, 사용성은 더 나빠졌다.

아래로 옮기면 몰아쓰기가 된다. 완전히 수동인 수집은 항목이 릴리스 시점에 기억으로부터 쓰인다는 뜻이다. 그것은 Keep a Changelog가 서두에서 경고하는 바로 그 모드이며, 조용히 악화된다. 체인지로그는 아무도 시간이 없었던 그 주가 오기 직전까지는 관리되고 있는 것처럼 보인다.

체인지로그 자동화 파이프라인은 어떤 모습인가

네 단계, 그리고 초안이 공개되는 지점에 정확히 하나의 사람 게이트를 둔다.

1. 병합 시점에 PR로부터 초안 항목을 도출한다. 라벨이나 커밋 접두사에서 나온 유형, 첫 초안으로서의 제목, PR로 돌아가는 링크, 기록된 작성자. 이것을 미출시 버킷에 놓는다.
2. 누구나 언제든 어떤 초안도 편집할 수 있으며, 편집은 저렴하다. 대부분은 한 줄만 다시 쓰인다.
3. 릴리스를 자르려면 버킷 안의 모든 항목이 편집되었거나 명시적으로 내부용으로 표시되어야 한다. 이 게이트가 설계의 전부다. 이것이 없으면 초안은 바쁜 주에 편집되지 않은 채로 출시된다.
4. 발행은 출시된 집합으로부터의 팬아웃이다. 공개 페이지, 피드, 이메일, 위젯, Slack 게시물. 하나의 원천, 여러 렌더링, 복사 없음.

3단계가 사람이 필요한 유일한 곳이며, 초안이 괜찮은 상태라면 릴리스당 약 십 분이 걸린다. 고객의 요청이 관련되어 있을 때, 초안은 그것이 닫는 issue도 함께 운반하며, 그것이 4단계가 요청자에게 알릴 수 있게 해주는 것이다. 기능 요망 템플릿은 그 링크가 살아남도록 설계되어 있다. 이 단계가 더 넓은 릴리스 흐름에서 어디에 놓이는지는 릴리스 관리 프로세스의 주제다.

자동화는 여러분의 데이터에 무엇을 요구하는가

체인지로그가 Markdown 파일이라면 위의 어느 것도 작동하지 않는다. 파일은 다시 파싱하지 않고는 다섯 개의 표면으로 렌더링될 수 없고, 산문을 파싱하는 것이 바로 제목의 절반만 보여주는 위젯으로 끝나는 이유이기 때문이다.

항목은 구조화되어야 한다. 유형, 날짜, 버전이나 릴리스 식별자, 대상 독자, 본문, 링크. 그러면 파일, 페이지, 피드, 이메일이 모두 뷰가 된다. 그 구조적인 지점이 도구를 선택하기 전에 제대로 해둘 가치가 있는 유일한 것이다. 나중에 값싸게 바꿔 넣을 수 없는 것이기 때문이다. 필요로 하는 모든 변경에 대해 실제로 항목이 만들어지지 않는 한 이 중 어느 것도 작동하지 않는다. CI에서 체인지로그 항목 의무화하기는 그 단계를 기억에 맡기는 대신, 항목 없는 머지를 파이프라인이 거부하게 만드는 방법을 다룬다.

우리는 changeloop을 만들고 있으며, 그곳에서 체인지로그는 먼저 피드이고 그다음이 페이지다. 그러니 이것을 공정한 추천이 아니라 이해관계로 읽어주기 바란다. 요금제는 카드 없이 시작하는 무료 저장소 하나이며, 그 형태를 보기에는 충분하다. 체인지로그 도구는 우리가 경쟁하는 제품을 포함해 그 밖에 무엇이 있는지에 대한 우리의 정리이며, 체인지로그 생성기는 파이프라인에 뛰어들기 전에 도출 과정을 보고 싶다면 브라우저에서 수집과 분류 단계를 처리해준다.

테스트

변경 사항이 병합된 시점부터 여러분의 저장소를 읽지 않는 고객에게 그 변경 사항이 보이게 되는 시점까지의 시간을 분 단위로 세어보라. 그 시간의 대부분이 누군가 도구 사이에서 텍스트를 복사하는 시간이라면, 여러분에게 필요한 자동화는 글쓰기가 아니라 발행에 있다.

FAQ

AI가 체인지로그를 쓸 수 있는가? 초안은 쓸 수 있다. 병합된 pull request를 받은 모델은 대부분의 경우 제목과 본문의 쓸 만한 첫 초안을 만들어내며, 이것은 수집과 분류 단계를 더 잘 해낸 것이다. 독자에게 알려야 할지 말지에 대한 선별, 그리고 최종 문구는 여전히 대상 독자를 아는 사람을 필요로 하며, 그 게이트 없이 초안을 발행하는 파이프라인은 잘못된 단계를 자동화한 것이다.

체인지로그 생성기와 체인지로그 자동화의 차이는 무엇인가? 생성기는 요청이 있을 때 한 번 커밋을 포맷된 목록으로 바꾼다. 자동화는 병합될 때마다 실행되며, 미출시 버킷을 유지하고, 사람의 검토를 릴리스의 조건으로 삼고, 하나의 원천으로부터 모든 표면에 발행한다. 생성기는 손으로 실행하는 파이프라인의 첫 단계다.

체인지로그는 커밋으로부터 자동화해야 하는가, pull request로부터 자동화해야 하는가? 변경 단위가 PR인 pull request로부터다. 제목과 설명은 변경 사항 전체에 대해 한 번 쓰이고, PR은 그것이 닫는 issue를 링크한다. 커밋 기반 도출은 커밋이 단위이고 관례에 따라 쓰일 때 작동한다.

자동화가 내부 변경 사항을 발행하지 못하게 하려면 어떻게 해야 하는가? chore, ci, test, refactor, 의존성 업데이트를 기본적으로 내부용으로 분류하고, 공개로 승격시키는 것을 의도적인 행위로 만들어라. 그 반대의 기본값, 즉 누군가 숨기지 않는 한 공개라는 방식이 bump deps가 고객에게 도달하는 방식이다.

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

changeloop 관련 페이지: changelog 도구 비교, changelog 생성기