깃허브·깃랩에 거릿식 스택 PR을 입히는 도구 'Maiao'

코드 리뷰 방식은 크게 두 갈래로 나뉜다. 하나는 깃허브나 깃랩처럼 브랜치 단위로 여러 커밋을 묶어 하나의 풀 리퀘스트(PR)로 올리는 방식이고, 다른 하나는 구글이 오래 써 온 거릿(Gerrit)처럼 커밋 하나하나를 독립된 리뷰 단위로 다루는 방식이다. 후자는 큰 기능을 잘게 쪼개 순차적으로 검토할 수 있다는 장점이 있지만, 대부분의 팀이 실제로 쓰는 호스팅은 깃허브 계열이라 거릿식 흐름을 그대로 옮기기 어려웠다. Maiao는 바로 이 간극을 메우려는 커맨드라인 도구다.

Maiao는 git 서브커맨드 형태의 git review 명령을 제공한다. 핵심 아이디어는 이른바 '스택드 디프(stacked diffs)' 방법론으로, 하나의 큰 변경을 작은 커밋들로 나누고 각 커밋을 각각의 PR 또는 MR로 만들어 서로 쌓아 올리는 것이다. 예컨대 커밋 세 개를 올리면 세 개의 PR이 생성되고, 이들이 순서대로 의존 관계를 갖는 스택으로 연결된다. 리뷰어는 거대한 변경 덩어리를 한꺼번에 보는 대신 논리적으로 구분된 단위를 차례로 검토할 수 있고, 작성자는 앞선 커밋에 대한 리뷰 피드백을 받는 동안에도 뒤이은 작업을 이어갈 수 있다.

여러 호스팅을 한 명령으로

Maiao가 내세우는 강점은 지원 범위다. 깃허브와 깃랩은 물론 Gitea, Forgejo, Bitbucket Cloud, 그리고 Cursor Origin까지 아우른다. 리모트 URL을 보고 알려진 호스트(github.com, gitlab.com, codeberg.org, bitbucket.org, origin.cursor.com)는 제공자를 자동으로 판별하며, 자체 호스팅한 사내 인스턴스라면 최초 사용 시 한 번 물어본 뒤 그 선택을 git config의 maiao.provider 값으로 저장해 재사용한다. 사내에 깃랩을, 오픈소스 작업에는 깃허브를 쓰는 식으로 여러 환경을 오가는 개발자에게는 도구 하나로 동일한 리뷰 흐름을 유지할 수 있다는 점이 실질적인 이점이다.

스택 처리 방식에서 눈여겨볼 대목은 깃허브의 네이티브 스택 기능을 '점진적 개선(progressive enhancement)'으로 취급한다는 설계다. PR을 두 개 이상 올리면 Maiao가 깃허브의 Stacks API를 조회해(결과는 24시간 캐싱한다) 지원되는 환경이라면 해당 PR들을 정식 스택으로 등록한다. 반면 이 API가 없는 구형 깃허브 엔터프라이즈 인스턴스에서는 이 단계를 조용히 건너뛰고, 대신 브랜치 기반의 스택 연결 방식으로 동작한다. 즉 최신 기능이 있으면 활용하되, 없어도 기본 흐름은 깨지지 않도록 이중으로 대비해 둔 셈이다.

프로젝트의 성격과 유지보수 상황

Maiao를 도입하려는 팀이라면 프로젝트의 계보도 함께 살펴봐야 한다. 지금의 저장소(runetes/maiao)는 원래 아드비인타(Adevinta)가 공개했던 프로젝트의 커뮤니티 포크다. 원 관리자들이 아드비인타를 떠나면서 상류(upstream) 저장소가 더 이상 활발히 유지되지 않게 됐고, 현재는 이 포크가 개발을 이어받은 상태다. 라이선스는 MIT이며, 기여를 환영한다는 안내와 CONTRIBUTING.md, 별도의 DISCLAIMER.md 문서를 두고 있다. 이름인 'Maiao'는 작은 커밋과 정갈한 PR을 지향한다는 의미에서 작은 섬의 이름을 따왔다고 소개한다.

실무 관점에서 스택드 디프 방식은 분명한 장점과 대가를 함께 가진다. 큰 기능을 작게 쪼개 리뷰 부담을 낮추고 리뷰 품질을 끌어올리는 것은 오래전부터 검증된 접근이며, Maiao는 그 흐름을 깃허브 계열 도구에 자연스럽게 얹어 준다. 다만 커밋을 항상 리뷰 가능한 단위로 유지해야 하는 규율은 팀 문화의 뒷받침을 요구하고, 여러 PR이 사슬처럼 엮이면 앞 단계 수정이 뒤 단계에 파급되는 리베이스와 재정렬 작업이 잦아질 수 있다. 스택 관리에 익숙하지 않은 팀이라면 초기 학습 비용을 감안해야 한다.

또 하나 냉정하게 짚을 부분은 지속성이다. 원 프로젝트가 관리 주체를 잃고 커뮤니티 포크로 명맥을 잇고 있다는 사실은, 팀의 리뷰 파이프라인이라는 중요한 축을 이 도구에 맡길 때 반드시 고려해야 할 위험 요소다. 깃허브 Stacks API 지원 여부에 따라 동작이 달라지는 점, 자체 호스팅 환경에서의 검증 필요성까지 함께 저울질하는 편이 좋다. 결국 Maiao는 거릿 스타일 리뷰의 이점을 익숙한 깃허브·깃랩 위에서 시험해 보고 싶은 팀에게 가벼운 진입점이 되어 주지만, 프로덕션 도입은 소규모 검증을 거친 뒤 판단하는 것이 합리적이다.