풀 리퀘스트

코드를 고칠 때는 본류에서 갈라낸 브랜치에서 작업합니다. 본류에서 갈라 따로 작업하는 줄기인데, 다 고친 뒤에 그것을 본류로 되돌려 넣는 순간이 옵니다. 이 순간에 아무 절차가 없으면 두 가지가 사라집니다. 합치기 전에 다른 사람이 볼 기회와, 왜 그렇게 고쳤는지에 대한 기록입니다.

페이지덱 초기에 태오가 그렇게 일했습니다. 고친 뒤 바로 본류에 합쳤습니다. 빠르고 편했는데 이틀 뒤 저장 오류가 났고, 문제를 찾는 데 하루가 들었습니다. 원인은 예외 처리 한 줄을 지운 것이었는데, 왜 지웠는지 물을 곳이 없었습니다. 기록에는 변경 자체만 남아 있고 그 판단의 이유는 태오의 기억에만 있었습니다.

풀 리퀘스트는 합치기 전에 한 자리를 만들어 두는 방식입니다. 이 변경을 합쳐 달라고 요청하면서, 무엇을 왜 고쳤는지 적고 자동 검사 결과를 붙이고 동료의 의견을 받습니다. 합친 뒤에도 그 자리는 남습니다. 반년 뒤에 같은 코드를 보는 사람이 여기까지 되짚어 올 수 있습니다.

한 요청에 다섯 가지가 들어갑니다. 앞의 둘은 사람이 쓰고 뒤의 셋은 도구가 채웁니다.

1. 제목 — 무엇을 했는지 한 줄로 적습니다. 목록에서 제목만 보고 무슨 변경인지 짐작할 수 있어야 합니다. 수정이나 개선 같은 말만 적힌 제목은 목록을 훑는 사람에게 아무것도 알려 주지 않습니다.
2. 설명 — 왜 고쳤는지, 무엇을 고쳤는지, 어떻게 확인했는지를 적습니다. 왜가 가장 중요합니다. 무엇을 고쳤는지는 코드를 보면 알 수 있지만 왜 그렇게 골랐는지는 여기 적지 않으면 사라집니다. 관련된 작업 항목이나 문의 번호를 함께 걸어 두면 배경까지 이어집니다.
3. 변경 내용 — 파일별로 어느 줄이 어떻게 달라졌는지 자동으로 표시됩니다. 여기서 관리할 것은 크기입니다. 바뀐 줄이 400줄을 넘으면 리뷰가 형식적으로 변하는 경향이 알려져 있습니다. 읽는 사람이 집중을 유지하지 못해 눈에 띄는 것만 지적하고 넘어갑니다.
4. 자동 검사 결과 — 단위 테스트와 린터 결과가 붙습니다. 단위 테스트는 함수나 모듈 하나를 떼어 확인하는 테스트이고, 린터는 코드 규칙 위반을 자동으로 잡아 주는 도구입니다. 사람이 볼 필요가 없는 것을 도구가 먼저 걸러 주는 자리입니다.
5. 리뷰어와 합치기 조건 — 누가 봐야 하는지와 무엇이 충족되면 합칠 수 있는지입니다. 검사 통과와 승인 한 건처럼 조건을 미리 정해 두면 합칠 때마다 협의하지 않습니다.

아직 볼 필요가 없는 상태로 올려 두는 초안 기능도 씁니다. 방향이 맞는지만 먼저 묻고 싶을 때, 작업이 반쯤 된 상태에서 올려 의견을 받고 나중에 정식 검토로 바꿉니다.

쓰는 사람은 코드를 고친 개발자입니다. 설명을 쓰는 데 5분이 드는데 그 5분이 읽는 사람의 30분을 줄여 줍니다. 같은 변경을 두 사람이 설명할 때 걸리는 시간 차이가 여기서 생깁니다.

읽는 쪽은 넷입니다.

1. 리뷰어가 첫 독자입니다. 합치기 전에 동료가 코드를 살펴보는 절차가 코드 리뷰이고, 그 절차가 이 자리에서 일어납니다.
2. 자동화 도구가 사람보다 먼저 읽습니다. 변경을 자주 합치고 자동으로 검증하는 방식인 지속적 통합이 걸려 있으면, 요청이 올라온 직후에 검사가 돌고 결과가 붙습니다.
3. 나중에 그 코드를 보는 사람이 읽습니다. 왜 이렇게 되어 있는지 궁금할 때 그 줄이 들어온 요청을 찾아 설명과 대화를 읽습니다. 실무에서 이 용도가 리뷰만큼 값을 합니다.
4. 만드는 일정을 보는 쪽도 목록을 봅니다. 올라온 지 오래된 요청이 쌓여 있으면 합치는 단계가 막혀 있다는 신호입니다.

오래 열려 있는 요청은 그 자체로 비용입니다. 본류가 계속 바뀌는 동안 갈라진 채로 두면 같은 곳을 다르게 고쳐 자동으로 합칠 수 없는 상태인 충돌이 늘어납니다.

"이 요청 1,200줄인데요. 두세 개로 쪼개서 올려 주세요."

크기가 커서 제대로 검토할 수 없다는 요청입니다.

"설명에 왜 이렇게 했는지가 없어요. 코드만 보고는 판단이 안 됩니다."

변경의 이유를 적어 달라는 지적입니다.

"초안으로 올려 뒀습니다. 방향만 먼저 봐 주세요."

완성 전에 의견을 받으려고 올렸다는 표시입니다.

페이지덱은 그 저장 오류 이후로 본류에 직접 합치는 것을 막고 요청을 거치게 했습니다. 태오가 같은 예외 처리를 다시 지우는 변경을 올렸을 때, 설명 칸에 그 줄이 왜 필요 없다고 판단했는지를 적었습니다. 리뷰에서 다른 개발자가 그 판단의 전제가 특정 조건에서만 맞는다는 것을 짚었습니다.

그 대화가 요청에 남아 있어서, 넉 달 뒤 비슷한 문의가 들어왔을 때 같은 논의를 다시 하지 않았습니다. 그때 걸린 시간은 하루가 아니라 20분이었습니다.

코드가 완성된 뒤에만 올리는 것이라고 보는 경우가 가장 많습니다. 검토를 받는 자리이니 완성품을 올려야 할 것 같습니다. 그런데 방향이 틀렸을 때 그 사실을 아는 시점이 늦어집니다. 사흘 작업한 것을 올리고 접근이 잘못됐다는 말을 들으면 사흘이 날아갑니다. 초안으로 먼저 올려 방향만 확인하면 그 위험이 줄어듭니다. 완성 뒤에만 올리는 관행을 그대로 두면 큰 요청이 늘어나고, 큰 요청은 다시 리뷰를 형식적으로 만듭니다.

크게 묶어 올리는 것이 효율적이라고 보는 것도 흔합니다. 요청을 만들고 검토받는 데 드는 시간이 매번 들기 때문입니다. 하지만 검토에 드는 시간은 크기에 비례해 늘지 않고 어느 지점을 넘으면 급히 꺾입니다. 400줄을 넘긴 요청은 보통 대충 읽히고, 대충 읽힌 요청에서 나온 문제는 합친 뒤에 발견돼 고치는 비용이 훨씬 큽니다. 작게 쪼개면 검토 횟수는 늘지만 한 번에 드는 시간이 짧아 전체가 줄어듭니다.