Git의 데이터 모델 (그리고 그 외 문서 업데이트)
안녕하세요! 지난 가을, Git 문서 작업을 위해 시간을 좀 내보기로 했어요. 오픈소스 문서를 다뤄보고 싶다는 생각은 오래전부터 해왔는데요, 보통은 어떤 문서가 개선될 수 있겠다고 생각하면 블로그 글이나 zine 같은 걸 따로 작성하곤 했어요. 그런데 이번에는 이렇게 생각해 봤어요. 공식 문서를 직접 조금 개선해 보면 어떨까?
그래서 Marie와 함께 Git 문서에 몇 가지 변화를 줬어요!
Git의 데이터 모델
문서 작업을 좀 하다 보니, Git이 문서에서 “object”, “reference”, “index” 같은 용어를 자주 쓰면서도 정작 그 용어들이 무슨 뜻인지, “commit”이나 “branch” 같은 다른 핵심 개념과 어떻게 연결되는지에 대한 제대로 된 설명은 없다는 걸 알게 됐어요. 그래서 새로운 “데이터 모델” 문서를 작성했어요!
지금은 여기에서 데이터 모델을 읽을 수 있어요. 아마 어느 시점엔가(다음 릴리스 이후겠죠?) Git 웹사이트에서도 볼 수 있게 될 거예요.
이 작업이 특히 기대되는 이유는, Git이 커밋과 브랜치 데이터를 어떻게 구성하는지 이해하는 것이 지난 몇 년간 Git의 동작을 파악하는 데 정말 큰 도움이 됐기 때문이에요. 그리고 정확하면서도 짧은(1600단어!) 데이터 모델 문서가 있다는 건 중요하다고 생각해요.
그런데 “정확하다”는 게 생각보다 쉽지 않았어요. Git 데이터 모델의 기본은 알고 있었지만, 리뷰 과정에서 새로운 세부 내용을 많이 배우게 됐고 꽤 많은 부분을 수정해야 했거든요(예를 들면 병합 충돌이 스테이징 영역에 어떻게 저장되는지 같은 부분이에요).
git push, git pull 등의 업데이트
그리고 Git의 핵심 man 페이지 중 일부의 서론 부분도 업데이트했어요. 곧바로 깨달았는데, “그냥 제 판단대로 개선해 보자”는 방식으로는 안 되겠더라고요. 유지관리자들이 왜 제 버전이 더 낫다고 믿어줘야 할까요?
오픈소스 문서 변경을 논의할 때 이런 문제를 자주 봤어요. 소프트웨어를 잘 아는 두 사용자가 설명이 명확한지 아닌지를 두고 논쟁하는 거예요(“X 방식으로 설명하면 좋을 것 같아요! 음, 저는 Y 방식이 더 낫다고 생각하는데요!”).
이런 방식은 별로 생산적이지 않다고 생각해요(소프트웨어에 익숙한 전문가는 자신의 설명이 초보자에게 명확하게 다가갈지를 판단하는 데 유난히 서툴거든요). 그래서 man 페이지의 문제점을 좀 더 근거를 가지고 찾아낼 방법이 필요했어요.
테스트 독자를 통해 문제 찾기
Mastodon에서 테스트 독자를 모집해 현재 버전의 문서를 읽고 헷갈리는 점이나 궁금한 점을 알려달라고 부탁했어요. 약 80명의 테스트 독자가 댓글을 남겨줬고, 정말 많은 걸 배울 수 있었어요!
정말 훌륭한 피드백이 많이 쏟아졌는데요, 예를 들면 이런 것들이었어요.
- 이해하지 못한 용어(pathspec이 뭐죠? “reference”는 무슨 뜻인가요? “upstream”은 Git에서 특별한 의미가 있나요?)
- 헷갈리는 특정 문장
- 추가했으면 하는 내용에 대한 제안(“저는 X를 늘 하는데, 여기 포함되면 좋겠어요”)
- 불일치(“여기서는 X가 기본값이라고 하는데, 다른 곳에서는 Y가 기본값이라고 하네요”)
테스트 독자 대부분은 Git을 최소 5~10년은 사용해 온 분들이었는데, 그게 정말 잘 맞아떨어졌다고 생각해요. Git을 5년 넘게 꾸준히 써온 사람들이 문장이나 용어를 도저히 이해할 수 없다고 하면, 문서를 더 명확하게 고쳐야 한다는 걸 주장하기가 훨씬 쉬워지거든요.
“소프트웨어 사용자들에게 기존 문서에 대해 코멘트를 받고, 그들이 찾은 문제를 고친다”는 이 패턴이 정말 잘 작동한다고 느꼈고, 앞으로도 다시 시도해 보고 싶어요.
man 페이지 변경 내용
결국 다음 4개의 man 페이지를 업데이트했어요.
git push와 git pull 변경이 개인적으로 가장 흥미로웠어요. 해당 페이지의 서론을 업데이트하는 것 외에도, 결국 다음 내용도 작성했거든요.
- “upstream branch”라는 용어가 무슨 뜻인지 설명하는 섹션(이전에는 제대로 설명되어 있지 않았어요)
- “push refspec”이 무엇인지 깔끔하게 정리한 설명
이런 변경 작업을 하면서 오픈소스 문서를 유지 관리하는 일이 얼마나 많은 노력을 필요로 하는지 새삼 느끼게 됐어요. 명확하면서도 정확한 글을 쓰는 건 쉽지 않고, 때로는 타협해야 할 때도 있더라고요. 예를 들어 “git push는 현재 브랜치에 upstream을 설정하지 않았다면 push.default 설정에 따라 실패할 수 있다.”라는 문장은 조금 모호한데, “따라”가 정확히 무엇을 의미하는지에 대한 세부 내용은 정말 복잡해서 그걸 다 풀어내는 것만 해도 큰 작업이거든요.
Git에 기여하는 과정에 대해
Git의 개발 과정을 이해하는 데 시간이 좀 걸렸어요. 여기서는 그 과정을 자세히 설명하진 않을게요(그건 따로 한 편의 글이 될 수 있을 테니까요!). 대신 몇 가지 간단한 메모만 남겨요.
- Git에는 Discord 서버가 있고, 기여를 시작하는 데 도움을 주는 “my first contribution” 채널이 있어요. Discord에서 사람들이 정말 따뜻하게 맞아주더라고요.
- 모든 기여에는 GitGitGadget을 사용했어요. 덕분에 제가 익숙한 방식인 GitHub 풀 리퀘스트를 만들면, GitGitGadget이 이를 Git 개발자들이 사용하는 방식(패치가 첨부된 이메일)으로 변환해 줬어요. GitGitGadget은 정말 잘 동작했고, 이메일로 패치를 보내는 법을 굳이 배우지 않아도 돼서 정말 감사했어요.
- 그 외에는 평소에 쓰는 이메일 클라이언트(Fastmail 웹 인터페이스)를 사용해 이메일에 답장했고, 메일링 리스트 관례에 맞춰 텍스트를 80자 단위로 줄 바꿈했어요.
그리고 lore.kernel.org에 있는 메일링 리스트 아카이브는 탐색하기가 어렵더라고요. 그래서 긴 메일링 리스트 스레드를 더 쉽게 읽을 수 있도록 제가 직접 만든 git list viewer를 급조했어요.
기여 과정을 헤쳐나가고 변경 내용을 리뷰하는 데 많은 분이 도움을 주셨어요. Emily Shaffer, Johannes Schindelin(GitGitGadget의 저자), Patrick Steinhardt, Ben Knoble, Junio Hamano를 비롯한 모든 분께 감사드려요.