docs: add a release runbook and a roadmap - #24
Merged
Conversation
Two things a maintainer needs before touching this repo did not exist here: how to cut a release, and what is left to do. Both lived only in people's heads, which is how the 3.2.0 mistake happened on 2026-08-09 — `VERSION=3.2.0-SNAPSHOT` was read as "3.2.0 is unreleased", when it means "3.2.0 shipped and 3.3.0 is being built". Two security fixes went onto main under a number already on Maven Central. Nothing shipped wrongly only because the tag was never moved. docs/releasing.md opens with that trap, and with the commands that answer it from the registry instead of the file. It also states the rule the recovery depended on: a published version is immutable, so do not move the tag and do not edit its changelog section — restore the section from the tag and open a new version. Then the six release surfaces, with the note that a BEHAVIOUR change can need more than a version bump in devslab-examples: 3.3.0's Redirect.NEVER requirement left the jdkhttp demo compiling but its comment false. docs/roadmap.md answers "what now". Today that is one item — OkHttp redirect hops — written up with the reasoning rather than as a task, so the next attempt does not repeat mine: a network interceptor looks like the seam and is not one, because OkHttp invokes it AFTER the connection is established. That fix would have passed review and been wrong. Both carry a Standing practice / parity pointer: walk the sibling's parity checklist whenever core logic changes here, and compare behaviour rather than source — reading the two implementations side by side is how the 3.1.1 bypass survived review in both libraries at once. Bilingual, in the mkdocs nav, and linked from both READMEs. Verified: ./gradlew build BUILD SUCCESSFUL, 239 tests, failures=0.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
메인테이너가 이 repo를 건드리기 전에 알아야 할 두 가지가 여기 없었습니다: 릴리스를 어떻게 내는지, 그리고 뭐가 남았는지. 둘 다 사람 머릿속에만 있었고, 그래서 어제 3.2.0 사고가 났습니다.
런북이 맨 앞에 놓는 것
VERSION=3.2.0-SNAPSHOT을 "3.2.0 미출시" 로 읽었는데, 실제 뜻은 "3.2.0은 나갔고 3.3.0을 만드는 중" 이었습니다. 보안 수정 2건이 이미 Maven Central에 있는 번호 아래로 main에 올라갔습니다. 태그를 옮기지 않았기 때문에만 잘못 나간 게 없었습니다.그래서 문서가 파일 대신 레지스트리에 물어보는 명령으로 시작합니다:
그리고 복구가 의존했던 규칙을 명시합니다 — 출시된 버전은 불변이니 태그를 옮기지도, 그 버전의 changelog를 고치지도 말고, 섹션을 태그에서 복원하고 새 버전을 열 것.
그다음 릴리스 6표면, 그리고 devslab-examples에서 동작 변경은 버전 범프만으로 부족할 수 있다는 메모 — 3.3.0의
Redirect.NEVER요구 때문에 jdkhttp 데모는 컴파일은 되는데 주석이 거짓이 됐던 실제 사례입니다.로드맵은 "이제 뭐 하지"에 답합니다
오늘 기준 항목은 하나 — OkHttp 리다이렉트 홉 — 인데, 작업 목록이 아니라 근거와 함께 적었습니다. 다음 사람이 제 실수를 반복하지 않도록:
그리고 잔여 위험이 좁다는 것(
Dns계층이 홉마다 호스트·사설 IP는 여전히 검사)도 함께 적어서, 급한 일로 오해되지 않게 했습니다.상시 관행
두 문서 다 정합성 포인터를 답니다 — 여기서 코어 로직이 바뀌면 자매의 체크리스트를 훑고, 소스가 아니라 동작을 대조할 것. 두 구현을 나란히 읽는 건 애초에 3.1.1 우회가 양쪽에서 동시에 리뷰를 통과한 방식입니다.
형태
양어(
.md+.ko.md), mkdocs nav 등록, 양쪽 README에서 링크.검증
./gradlew buildBUILD SUCCESSFUL, 239 tests, failures=0.