Changeloop

changeloop 블로그

실전 릴리스 노트

저희가 자주 고민하는 두 가지가 있습니다. 누군가 읽는 릴리스 노트를 쓰는 법, 그리고 changelog를 손으로 관리하지 않는 법입니다. 뉴스레터도, 가입도 없습니다. 글만 있습니다.

  • 버그 수정 릴리스 노트, 쓸모 있는 항목을 쓰는 법

    버그 수정 릴리스 노트는 항목마다 증상, 영향받은 대상, 다음에 할 일을 밝혀야 읽힌다. 전후 사례와 보안 수정, 데이터 손실 수정 규칙을 정리했다.

    실전 릴리스 노트5분 분량

  • 소프트웨어 제품에서 고객 피드백을 요청하는 방법

    사용자가 무언가를 막 끝낸 직후, 그 자리에서 구체적인 질문 하나를 던져라. 순간별로 쓸 수 있는 문구와 피해야 할 나쁜 요청 방식을 정리했다.

    피드백 루프6분 분량

  • 제품 로드맵 예시 여섯 가지와 각각이 실패하는 이유

    Now/Next/Later, 분기별, 테마, 성과, 공개, 릴리스 로드맵까지 여섯 가지 제품 로드맵 예시를 보여주고, 각각 어떤 팀에 맞고 어디서 무너지는지 정리한다.

    피드백 루프5분 분량

  • 자주 배포하는 팀을 위한 릴리스 관리 프로세스

    소프트웨어 팀을 위한 릴리스 관리 프로세스를 범위 계획부터 회고까지 일곱 단계로 나누고, 단계마다 담당자와 완료 기준을 정했다. DORA 지표도 소개한다.

    엔지니어링6분 분량

  • 모든 종류의 변경에 쓸 수 있는 릴리스 노트 예시

    새 기능, 수정, 파괴적 변경, 보안 수정, 비추천, 앱스토어 노트, 내부 노트까지 변경 종류별 릴리스 노트 예시와 그 문구가 효과적인 이유를 보여준다.

    실전 릴리스 노트5분 분량

  • Stripe API 버전 관리, 작동 방식과 따라 할 점

    Stripe API 버전 관리는 계정마다 날짜 기반 버전을 고정하고 요청마다 헤더로 덮어쓸 수 있게 한다. 작동 방식과 유지 비용, 작은 API가 따라 할 점을 설명한다.

    API 변경5분 분량

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

    체인지로그는 누가 쓰는가? PR 작성자는 무엇이 바뀌었는지 알고 PM은 왜 중요한지 안다. 어느 쪽도 혼자서는 쓸모 있는 항목을 쓸 수 없다.

    엔지니어링4분 분량

  • 긴급 릴리스 노트: 실시간 시간 압박 속에서 쓰기

    인시던트로 시작된 긴급 릴리스는 며칠이 아니라 몇 분 안에 노트가 필요하다. 평소의 작성 과정은 없는 시간을 전제로 하므로 무엇을 남기고 자를지 설명한다.

    실전 릴리스 노트4분 분량

  • Protobuf 브레이킹 체인지: 와이어에서 살아남는 것

    Protobuf 파괴적 변경은 URL이 아니라 와이어 위에서 일어난다. 어떤 gRPC 필드 변경은 공짜지만 다른 변경은 모든 클라이언트를 조용히 망가뜨린다.

    API 변경5분 분량

  • 체인지로그 파일 형식, JSON인가 YAML인가 그냥 Markdown인가

    체인지로그 파일의 형식은 페이지와 위젯을 공급할 수 있는지 사람만 읽는지를 정한다. Markdown, JSON, YAML이 각각 치르는 대가를 비교한다.

    엔지니어링4분 분량

  • 중복된 기능 요청, 목소리를 잃지 않고 병합하기

    중복된 기능 요청을 묶으면 개수는 지키지만, 부주의하게 병합하면 유용했던 표현이 사라진다. 표현을 지키는 병합과 잘못된 일치를 가려내는 법을 다룬다.

    피드백 루프4분 분량

  • 버전 번호 없는 GraphQL 비추천 처리

    GraphQL은 URL에 v1이나 v2가 없고 필드를 지시어로 하나씩 비추천 처리한다. 이는 체인지로그가 지는 책임을 바꾼다. 파괴적 변경과 안전한 제거법을 다룬다.

    API 변경4분 분량

  • API 마이그레이션 가이드는 어떻게 작성하는가

    API 마이그레이션 가이드는 호환되지 않는 변경을 장애가 아니라 체크리스트로 바꾼다. 무엇이 필요한지, 언제 써야 하는지, 왜 항목 하나로는 부족한지 설명한다.

    API 변경4분 분량

  • GitHub Actions용 체인지로그 체크

    GitHub Actions 체인지로그 체크는 항목 없는 머지를 막는다. 기억에 의존하면 일정 앞에서 실패하는 이유와 체크 자체가 깨뜨리는 것을 다룬다.

    엔지니어링4분 분량

  • 고객을 잃지 않고 기능 요청을 거절하는 방법은 무엇인가

    루프를 닫는다는 것은 보통 요청이 출시되었다고 알리는 일이다. 더 어려운 쪽은 관계를 해치지 않고 거절하는 일이며, 좋은 거절이 말해야 할 것을 설명한다.

    피드백 루프4분 분량

  • 기능 요청을 놓치지 않고 추적하는 방법

    기능 요청 추적은 어디에도 도달하지 못하거나 아무도 보지 않는 곳에 쌓여서 실패한다. 두 실패를 견디는 체계와 쓸모 있는 라벨 붙이는 법을 설명한다.

    피드백 루프4분 분량

  • 기능 요청이 실제로는 버그 신고일 때

    새 설정을 요청하는 지원 티켓은 숨겨진 버그를 우회하는 방법일 수 있다. 잘못된 라벨은 티켓을 엉뚱한 담당자와 대기열로 보낸다. 구별법과 판단할 사람을 다룬다.

    피드백 루프4분 분량

  • 피처 플래그 릴리스 노트: 무엇을, 언제 말하는가

    피처 플래그 릴리스 노트는 머지와 출시를 구분해야 한다. 잘못된 시점에 루프를 닫으면 사용자가 아직 볼 수 없는 기능을 알리게 된다. 판단 기준을 짚어본다.

    피드백 루프4분 분량

  • 지원 티켓 대 기능 요청: 무엇을 신뢰해야 하는가

    지원 티켓과 기능 요청 게시판은 서로 다른 것을 측정한다. 한쪽의 급증을 다른 쪽의 급증과 똑같이 취급하면 자신만만하지만 잘못된 우선순위가 나온다.

    피드백 루프4분 분량

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

    Git 태그, 릴리스, 체인지로그 항목은 하나의 사건에 대한 세 가지 기록이다. 이를 혼동하면 체인지로그가 실제 릴리스에서 벗어난다. 맞추는 법을 설명한다.

    엔지니어링4분 분량

  • 내부용 API 체인지로그: 다른 팀에게 무엇이 달라지는가

    공개 API 체인지로그에는 직접 연락할 수 없는 독자가 있고, 내부용에는 두 층 떨어진 독자가 있다. 이 차이가 체인지로그의 책임을 어떻게 바꾸는지 짚어본다.

    API 변경4분 분량

  • 내부용 릴리스 노트: 그 밖에 누가 알아야 하는가

    지원팀과 영업팀은 보통 당황한 고객에게서 출시 소식을 듣는다. 내부용 릴리스 노트는 이를 해결하며, 고객용 노트와는 다른 형태로 먼저 도착해야 한다.

    실전 릴리스 노트4분 분량

  • 모바일 앱 릴리스 노트: 글자 수 제한이 무엇을 잘라내는가

    앱스토어와 플레이스토어는 눈에 보이는 몇 줄만 주고 링크는 허용하지 않는다. 웹 체인지로그에서 통하던 방식이 깨지므로 무엇을 의도적으로 자를지 설명한다.

    실전 릴리스 노트4분 분량

  • 모노레포 체인지로그: 하나로 합칠까, 패키지마다 따로 둘까

    모노레포는 저장소 전체를 위한 체인지로그 하나나 패키지마다 하나를 둘 수 있다. 잘못 고르면 릴리스가 너무 시끄럽거나 흩어진다. 기준은 구조가 아니라 독자다.

    엔지니어링4분 분량

  • 새 기능을 어떻게 발표해야 하는가 (침묵 없이)

    대부분의 기능 발표는 아무도 두 번 읽지 않는 채널에서 조용히 죽는다. 어디서 발표하고 무엇을 먼저 말할지, 요청했던 사람에게 어떻게 닿을지 설명한다.

    실전 릴리스 노트4분 분량

  • 계속 쌓이는 기능 요청에 우선순위를 매기는 방법

    백로그를 추적하고 묶고 라벨을 붙여도 어떤 요청을 먼저 내보낼지라는 질문은 남는다. 쓸 만한 프레임워크와 한계, 투표 수가 감추는 것을 짚어본다.

    피드백 루프4분 분량

  • 엔터프라이즈 릴리스 노트: 한 계정에 무엇이 달라지는가

    엔터프라이즈 릴리스 노트는 비공개 빌드 위의 고객 인스턴스에 맞춰야 한다. 공개 블로그용을 그대로 보내면 고객이 혼란스러워지고 로드맵이 유출될 수 있다.

    실전 릴리스 노트4분 분량

  • 시맨틱 버저닝과 당신의 체인지로그, 함께 보기

    시맨틱 버저닝은 호출자가 체인지로그 항목을 읽기 전에 릴리스가 얼마나 아플지 알려준다. 각 숫자가 약속하는 것과 항목이 그에 대해 져야 할 책임을 설명한다.

    엔지니어링4분 분량

  • 웹훅 체인지로그, 아무도 요청하지 않은 파괴적 변경

    웹훅 페이로드 변경은 새 형태를 거부할 호출자가 없어 조용히 깨진다. 무엇이 파괴적 변경인지와 버전을 매기는 방법을 다룬다.

    API 변경4분 분량

  • API Sunset 헤더, 언제 보내야 하는가

    API Sunset 헤더는 비추천 공지와 달리 클라이언트에 버전이 응답을 멈춘다고 알린다. RFC 8594가 다루는 범위와 브라운아웃의 이점을 설명한다.

    API 변경4분 분량

  • 체인지로그란 무엇이고, 무엇이 들어가야 하는가

    체인지로그는 제품에서 무엇이 바뀌었는지 날짜순으로 기록한 것으로, 영향받는 사람들을 위해 쓴다. 무엇이 들어가고 어디에 두며 어떻게 배포할지 설명한다.

    실전 릴리스 노트4분 분량

  • API 체인지로그: 무엇을 공개하고 누가 읽는가

    API 체인지로그는 내 코드가 다음 달에도 작동할지 판단하려는 사람이 읽는다. 각 항목이 독자에게 져야 할 책임과 위치, 구독 방법을 설명한다.

    API 변경5분 분량

  • 사람들이 계속 찾아오는 체인지로그 페이지 만드는 법

    체인지로그 페이지는 사람들이 다시 돌아올 때 가치가 있다. 어디에 둘지, 항목에 무엇이 필요한지, 피드와 마크업, 위젯과의 관계를 설명한다.

    엔지니어링5분 분량

  • 실제로 읽히는 제품 업데이트 이메일 템플릿

    읽히는 제품 업데이트 이메일은 그것을 요청한 사람에게 도착한 이메일이다. 템플릿 구조, 네 가지 유형, 제목 짓는 법, 세그멘테이션과 동의를 설명한다.

    실전 릴리스 노트4분 분량

  • 개발자를 잃지 않고 API를 비추천 처리하는 방법

    비추천 처리는 날짜가 적힌 하나의 약속이다. 일정, 공지 템플릿, 응답 헤더, 서비스 종료가 사고로 번지지 않게 막는 한 단계를 설명한다.

    API 변경5분 분량

  • 호출자를 위한 API 버저닝 모범 사례

    부서지는 것만 버전으로 관리하고, 호출자가 볼 수 있는 곳에 버전을 두며, 예전 버전은 정해진 날짜까지 유지하자. 네 가지 방식을 비교한다.

    API 변경6분 분량

  • 파괴적 변경: 무엇이 해당하고 어떻게 출시하는가

    파괴적 변경은 올바른 호출자가 버티지 못하는 변경이다. 해당 여부, CI에서 잡는 법, 안전하게 출시하는 방법을 정리한다.

    API 변경7분 분량

  • 체인지로그 쪽에서 고객 피드백 루프를 닫는 방법

    피드백 루프는 요청한 사람에게 출시되었다고 알릴 때 닫힌다. 네 단계의 루프가 어디서 끊어지는지, 왜 체인지로그가 그것을 닫기에 알맞은지 설명한다.

    피드백 루프6분 분량

  • 체인지로그 항목이 되는 기능 요망 템플릿

    기능 요청은 출시되는 순간 다시 찾을 수 있어야 쓸모가 있다. 요청을 올바른 곳으로 보내는 라벨과 나중에 체인지로그가 읽을 필드를 살펴본다.

    피드백 루프4분 분량

  • issue 트래커로 만드는 세 개의 열로 이루어진 공개 로드맵

    공개 로드맵은 미래에 대한 약속이므로 작게 유지하고, 이미 추적하는 issue로 만들며, 항목은 issue에 붙인 라벨 하나로 열 사이를 옮기는 편이 좋다.

    피드백 루프4분 분량

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

    수집, 포맷팅, 발행은 자동화해도 좋지만 무엇을 선별하고 어떻게 쓸지는 자동화해선 안 된다. 그 경계선이 어디인지, 옮겨지면 어떻게 되는지 살펴본다.

    엔지니어링5분 분량

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

    체인지로그는 무언가를 찾아보는 사람을 위한 계속 이어지는 기록이고, 릴리스 노트는 관심을 가질지 판단하는 사람을 위해 선별한 메시지다.

    실전 릴리스 노트4분 분량

  • Conventional commits에서 체인지로그로

    Conventional commits는 체인지로그를 도출 가능하게 하지만 읽기 쉽게 만들지는 못한다. 이 관례가 사주는 것과 한계, 그 간극을 메우는 법을 살펴본다.

    엔지니어링4분 분량

  • 실제로 읽히는 릴리스 노트를 쓰는 방법

    버그 수정 및 성능 개선이라는 문구만으로는 릴리스 노트라고 할 수 없다. 모든 항목이 답해야 하는 하나의 질문과 실제 사례의 고치기 전후를 보여준다.

    실전 릴리스 노트5분 분량

  • Keep a Changelog, 실제로 적용해 보니

    Keep a Changelog 명세는 한 페이지이고 읽는 데 십 분도 걸리지 않지만, 구현하면서 대부분의 팀이 어긋난다. 명세가 말하는 것과 열어둔 것, 틀린 곳을 살펴본다.

    엔지니어링4분 분량

  • 지킬 가치가 있는 릴리스 노트 모범 사례

    릴리스 노트 모범 사례 목록의 대부분은 문체 조언에 지나지 않는다. 독자의 행동을 실제로 바꾸는 사례와 유행만 좇는 흔한 세 가지 사례를 살펴본다.

    실전 릴리스 노트5분 분량