체인지로그는 누가 쓰는가, 그리고 누가 써야 하는가

팀에게 누가 체인지로그를 쓰냐고 물으면 정직한 대답은 대개 “기억하는 사람 아무나”이며, 이것은 CI에서 체인지로그 항목을 강제하기가 기계적인 수준에서 고치려는 것과 똑같은 실패 방식이다. 하지만 항목이 존재하도록 강제하는 것이 누가 좋은 항목을 쓸 자격이 있는지를 결정해주지는 않으며, 그 질문을 건너뛰는 팀들은 대개 강제하기 가장 쉬운 사람, 보통 PR 작성자에게 기본값으로 넘기면서 그 사람이 정말 그것을 잘 쓸 수 있는 사람인지는 확인하지 않는다.

PR 작성자가 자동으로 최고의 체인지로그 작성자가 되지 않는 이유는 무엇인가

그녀는 구현을 알지만 반드시 영향을 아는 것은 아니고, 이것은 서로 다른 종류의 지식이기 때문이다. Conventional commits는 어디서 멈추는가는 이 간극을 커밋 메시지 쪽에서 다룬다. fix(auth): reject expired refresh tokens는 정확하지만 고객에게는 아무것도 말해주지 않으며, 그 수정을 쓴 사람은 종종 그것을 번역하기에 가장 부적합한 사람이다. 몇 시간 동안 그 버그의 관점에서 생각하느라 사용자가 실제로 무엇을 경험했는지에 대한 외부 시각을 잃어버렸기 때문이다. 이것이 테크니컬 라이터라는 직업이 존재하는 것과 같은 이유다. 구현을 영향으로 번역하는 것은 그것을 만드는 것과는 별개의 기술이며, 그 코드를 얼마나 잘 다루는 개발자든 상관없이 연습이 필요하다.

그렇다면 제품팀이나 지원팀이 대신 모든 항목을 써야 한다는 뜻인가

아니다, 그들은 정반대의 간극을 갖고 있기 때문이다. 사용자에게 무엇이 중요한지는 알지만 실제로 무엇이 출시되었는지는 항상 아는 것이 아니며, 이는 읽기는 쉽지만 때로 범위가 틀린 항목을 만들어낸다. 여전히 플래그 뒤에 있는 기능에 대해 “이제 X를 지원합니다”라는 주장, 혹은 세 가지 경우 중 하나만 다루면서 완료된 것으로 서술된 수정이 그렇다. 개발자가 쓴 항목의 실패 방식은 읽기 어렵지만 정확한 것이고, PM이 쓴 항목의 실패 방식은 읽기 쉽지만 검증되지 않은 것이다. 어느 역할도 좋은 항목에 필요한 것의 양쪽 절반을 모두 소유하고 있지 않다.

실제로 작동하는 소유권 모델은 어떤 모습인가

변경 사항에 가장 가까운 사람이 초안을 쓰고, 사용자에게 가장 가까운 사람이 검토하며, 모두가 다른 누군가가 문제를 잡아줄 거라고 가정하는 대신 한 명의 지정된 사람이 최종 문구에 책임을 지는 것이다. 초안은 훌륭할 필요보다 존재하고 정확할 필요가 더 크다. 개발자가 쓴, 무엇이 바뀌었는지를 정확히 말하는 거친 문장이 다듬어졌지만 검증되지 않은 것보다 더 나은 출발점이다. 명료함을 위해 다시 쓰는 것이 정확함을 위해 다시 쓰는 것보다 쉽기 때문이다. 검토 단계는 PM 또는 지원 리드가 초안을 읽고 가독성의 간극을 잡아내는 하나의 질문을 던지는 곳이다: 코드를 보지 않았어도 이것을 이해했을까.

항상 같은 사람이 책임져야 하는가, 아니면 순환해야 하는가

지정되고 안정적인 것이 순환하는 것을 이긴다, 적어도 최종 승인에 대해서는. 순환하는 소유자는 매번 팀의 관례를 처음부터 다시 유추하는 누군가가 각 항목을 검토한다는 것을 의미하며, 이는 정확히 목소리가 항목마다 표류하고 독자가 체인지로그가 위원회에 의해 쓰였다는 것을 알아차리기 시작하는 방식이다. 한 사람, 또는 매우 작고 안정적인 그룹은 시간이 지나면서 판단을 축적한다. 언제 “개선했습니다”라고 말하고 언제 구체적인 숫자를 언급할지, 언제 수정이 자기 항목을 필요로 하고 언제 배치에 묶어 넣을지. 그 판단은 작업을 균등하게 분배하는 것보다 더 가치가 있다.

초안 (개발자, PR에서):
"Fixed pagination cursor not respecting the `sort` param
in some edge cases."

검토됨 (체인지로그 소유자, 실제 PR과 대조함):
"수정됨: 날짜순으로 정렬된 내보내기가 첫 페이지를
넘어가면 순서가 뒤바뀐 결과를 반환할 수 있었습니다.
이제 모든 페이지에서 일관됩니다."

작은 팀은 한 줄의 텍스트를 위해 이렇게 많은 과정이 필요한가

별개의 사람으로서의 역할은 아니지만, 그 두 단계는 혼자서도 여전히 중요하다. 한 사람으로 이루어진 팀은 개발자이자 검토자이며, 그 규모에서 살아남는 규율은 검토를 별도의 정신적 단계로 수행하는 것이지, 수정을 쓰는 것에서 그 설명을 발행하는 것으로 한 호흡에 바로 건너뛰지 않는 것이다. 작은 규모의 함정은 두 번째 단계를 완전히 건너뛰는 것이지, 두 번째 사람이 없다는 것이 아니다. 외부의 아무도 그것을 강제하지 않기 때문이며, 그 단계가 잡아내기 위해 존재하는 정확성의 간극은 같은 사람이 이론적으로 자기 사각지대를 알아차릴 수 있다는 이유만으로 사라지지 않는다.

최종 항목에 아무도 책임지지 않으면 어떻게 되는가

체인지로그는 완전히 실패하는 대신 고르지 못하게 저하된다, 이것이 더 나쁜 이유는 독자가 지적할 때까지 아무도 알아차리지 못하기 때문이다. 어떤 항목은 그것을 쓴 사람이 신경 썼기 때문에 예리하게 남아 있고, 다른 항목은 그것을 쓴 사람이 빨리 움직였고 발행 전에 아무도 잡아내지 못했기 때문에 “다양한 개선 사항 및 버그 수정”처럼 모호해진다. Keep a Changelog의 형식 제약은 구조적 표류, 빠진 날짜, 잘못된 범주를 잡아내지만, 템플릿 안의 그 어떤 것도 기술적으로는 올바르게 형식이 갖춰진 모호한 항목을 잡아내지 못한다. 이것이 정확히 지정된 소유자가 메우기 위해 존재하는 간극이다.

FAQ

체인지로그 소유자는 엔지니어링 역할이어야 하는가, 제품 역할이어야 하는가? 둘 다 그 사람이 범위를 검증할 기술적 유창함과 외부 독자를 위해 쓸 만큼 구현으로부터의 충분한 거리를 모두 갖고 있다면 작동할 수 있다. 직함은 두 절반을 모두 해낼 수 있는지, 혹은 자신이 할 수 없는 절반에 대해 누구에게 물어봐야 할지 아는지보다 덜 중요하다.

온콜 같은 순환 일정이 체인지로그 소유권에 적합한 경우가 있는가? 분량에 대해서는 가끔, 팀이 너무 작아서 한 사람이 모든 것을 검토할 수 없다면 그렇다. 목소리와 판단에 대해서는 아니다, 그것이 정확히 순환이 침식시키는 것이기 때문이다. 안정적인 검토자 한 명을 유지하면서 초안 작성의 부담을 나누는 순환은 표류 없이 그 이점을 얻는다.

현재의 소유권 설정에 뭔가 잘못되었다는 가장 빠른 신호는 무엇인가? 정확하지만 읽기 어려운 항목, 혹은 읽기 쉽지만 범위가 틀린 항목이 누가 썼는지를 따르는 패턴으로 나타나는 것이다. 품질이 일관되게 유지되는 대신 작성자와 상관관계를 보인다면, 간극은 소유권에 있는 것이지 글쓰기 능력에 있는 것이 아니다.

자동화는 소유권이 얼마나 중요한지를 줄이는가? 필요한 글쓰기의 양을 줄이는 것이지, 필요한 판단의 양을 줄이는 것이 아니다. 체인지로그 자동화는 파이프라인이 안전하게 생성할 수 있는 것, 형식화, 발행, 크로스포스팅을 다룬다. 문구, 그룹화, 그리고 무엇이 언급할 가치가 있는지는 파이프라인의 얼마나 많은 부분이 자동화되었든 상관없이 인간의 결정으로 남는다.

PR 작성자와 검토자가 문구를 두고 의견이 갈리면 어떻게 하는가? 검토자의 판단을 따른다. 그들이 답하고 있는 질문, 즉 외부 독자가 이것을 이해할까라는 질문이 바로 그 역할이 지키기 위해 존재하는 것이기 때문이다. 그렇다고 개발자의 판단이 무가치하다는 뜻은 아니다. 의견 차이가 문구가 아니라 정확성에 관한 것이라면 검토자가 물러선다. 범위를 올바르게 맞추는 것은 작성자의 몫이기 때문이다. 문구와 정확성이라는 두 종류의 의견 차이를 구분하는 것만으로 이런 상황 대부분이 교착 상태로 번지는 것을 막을 수 있다.

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

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