1편에서 찾은 버그는 우리가 쓰는 Honcho 배포 안에서만 고치고 끝낼 수도 있었다. 실제로 그렇게 했다 — 코드를 고치고, 밀려 있던 문서 26,043건을 재처리하고, 테스트를 추가하고, 거기서 멈췄어도 아무 문제 없었을 것이다. Honcho는 우리가 자체 호스팅하는 오픈소스 프로젝트이고, 이 저장소는 원본 프로젝트를 그대로 내려받아 쓰는 쪽이라서다.
그런데 이 버그는 우리 배포만의 문제가 아니었다. pgvector만으로 Honcho를 운영하는 배포라면 누구든 똑같이 걸릴 구조적인 문제였다 — 재조정 로직 자체가 그 경로에서 문서를 아예 처리하지 않으니까. 그래서 고친 걸 원본 프로젝트에 PR로 보내기로 했다.
보낼 만한 수정인지부터 확인했다
무작정 PR을 올리기 전에 몇 가지를 먼저 확인했다. 커밋이 한 개로 깔끔하게 분리돼 있는지, 회귀 테스트가 같이 있는지, 이미 같은 문제를 리포트한 이슈가 있는지. 셋 다 확인해보니 커밋은 원인과 영향 범위를 설명하는 메시지와 함께 이미 정리돼 있었고, 테스트도 두 개(단위 테스트 하나, 재조정 사이클 전체를 검증하는 통합 테스트 하나) 붙어 있었다. 비슷한 이슈도 검색해봤지만 없었다 — 아직 아무도 리포트하지 않은 것 같았다.
원본 프로젝트의 기여 가이드는 흔한 방식이었다. 저장소를 포크하고, 브랜치를 만들고, 그 브랜치로 PR을 보내는 것. 포크는 예전에 이미 만들어져 있었다.
저장소를 만들 때 겪은 것과 같은 벽 — 403 권한 오류, SSH vs HTTPS 푸시
수정 브랜치를 포크 저장소에 올리려고 했더니 403 권한 오류가 났다. 접근은 되는데 쓰기 권한은 없는 토큰이었다. 이건 새로운 문제가 아니었다 — 다른 작업에서 새 GitHub 저장소를 만들려다 똑같은 종류의 권한 부족으로 막힌 적이 있었다. 그때는 저장소 생성 권한이 없었고, 이번엔 푸시 권한이 없었다. 원인은 같다 — 지금 쓰는 토큰이 세밀하게 범위가 제한된 토큰이라, 읽기 위주로만 설정돼 있고 쓰기가 필요한 동작 몇 가지는 빠져 있는 것이었다.
다행히 이번엔 우회로가 있었다. 같은 계정으로 SSH 인증은 이미 돼 있었고, 저장소 주소를 HTTPS 대신 SSH로 바꾸니 푸시가 바로 됐다. 토큰의 권한 범위와 SSH 키의 권한 범위가 서로 다르게 설정돼 있었던 셈이다.
브랜치는 올라갔지만 끝이 아니었다. 이번엔 PR 생성 자체가 같은 토큰 문제로 막혔다 — 커맨드라인 도구로 PR을 만들려 하니 “이 토큰으로는 PR 생성 API에 접근할 수 없다”는 응답이 돌아왔다. 푸시는 SSH로 우회했지만, PR 생성은 git 프로토콜이 아니라 GitHub API를 직접 호출하는 동작이라 SSH로는 우회가 안 됐다.
결국은 웹 화면으로
남은 방법은 브라우저에서 직접 만드는 것이었다. 포크와 원본 저장소를 비교하는 화면을 열고, 제목과 본문을 채워서 제출했다. 본문엔 수정 이유와 영향 범위, 이 버그를 어떻게 발견했는지, 그리고 정직하게 밝힌 한계도 적었다 — 이 저장소의 로컬 테스트 환경이 실제 운영 데이터베이스 설정과 달라서, 자동화된 테스트 스위트 전체를 돌려서 검증하지는 못했다는 점.
PR은 원본 저장소에 정상적으로 올라갔다. 이제 메인테이너의 리뷰를 기다리는 중이다.
두 번째로 겪은 벽이라 알아본 것
이번 권한 문제는 사실 새로 겪은 게 아니라, 다른 작업에서 이미 한 번 겪었던 것과 같은 원인이었다. 그때는 “저장소 생성 권한이 없구나”로 넘어갔는데, 이번에 같은 증상(403, 권한 부족)을 다시 만나고 나서야 이게 우연이 아니라 지금 쓰는 토큰 자체의 범위 문제라는 게 분명해졌다. 한 번은 예외처럼 보이던 게, 두 번째 겪고 나니 패턴으로 보인 것이다.
버그 하나를 고치는 것과, 그 수정을 원본 프로젝트에 돌려주는 것 사이엔 코드 자체와는 상관없는 절차가 여러 겹 있었다 — 기여 가이드를 읽고, 중복 여부를 확인하고, 권한 문제를 두 번 다른 방식으로 우회하고. 어느 것도 어렵지는 않았지만, 어느 것도 생략할 수 있는 단계는 아니었다.