더 나은 커밋, 더 나은 프로젝트 만들기

남은 2024년까지 2개의 프로젝트를 진행한다.

커밋을 atomic 하고 유의미하게 나눈다는 건 알지만 할 때마다 여전히 어렵다.

 

전에 커밋 컨벤션에 대해 한번 정리했지만

Github Blog에서 실제 커밋 트리를 보여주며 더 나은 커밋 작성하는 방법을 소개하고 있어 정리해 봤다.

 

 

 

Git Commit을 단순히 롤백하고 협업을 위한 코드 분리(?) 정도의 저장소로 생각하지 말고
지금의 코드가 만들어진 이야기를 얘기한다는 생각으로 Commit을 만들자!

 

 

https://github.blog/developer-skills/github/write-better-commits-build-better-projects/

Write Better Commits, Build Better Projects

---

개발을 하다 보면 코드 작성보다 코드 읽고 이해하는데 더 많은 시간을 할애한다.

주석이나 코드 스타일 가이드, 문서 등 코드 이해를 돕는 다양한 방법이 존재하지만

여전히 코드를 읽고 이해하는 건 어렵다.

 

운이 좋게도 위에서 소개한 방법과 함께 git을 사용하면 이 문제를 해결할 수 있다.

Git은 단순히 스냅샷이나 큰 프로젝트의 점진적인 진행을 기록하는 도구 이상의 힘이 있다.

 

커밋은 현재 레파지토리의 역사와 어떻게 지금 모습이 되었는지를 이야기해 준다.

 

1. 커밋을 구성하고 수정하는데 유용한 가이드라인을 소개하고
2. 이러한 가이드라인을 적용하기 위한 실용적인 접근 방식의 개요를 설명한다.
3. 마지막으로 잘 만들어진 커밋 기록의 실용적인 응용 사례를 설명한다.

 

좋은 커밋 작성하기

커밋에는 당신만의 스타일과 목적 그리고 수정한 컨텍스트가 담겨있다.

코드 작성 중에 제안하는 가이드라인 전부를 적용하지 못한다고 아쉬워말고
코드 작성이 끝난 후 반복적으로 코드 작성하면서 가이드라인을 적용할 수 있다.

 

첫 번째 문제

커밋의 변경사항이 연속적이지 않고 여기저기 흩어져 있다면 리뷰어는 코드 파악하는데 피곤할 것이다.

문제는 개발자는 유의미한 기능 파악을 할 때까지 재미있다와 좌절스럽다를 오가며

커밋을 왔다 갔다 하면서 작업 시간이 증가한다.

 

해결방법

커밋을 요약하고 의도에 맞게 재구성한다.

어떤 작업(커밋)을 할지는 당신에게 달려있긴 하지만 어떻게 구성하면 좋을지 몇 가지 팁을 소개한다.

 

※ 마지 A라는 주제에 대해 글 쓰듯이

브랜치를 딴 후 (책 주제) 이야기(커밋)를 써 내려간다.   단순 코드 저장소가 아니라..

 

feature/image-modifier 브랜치를 만들고 실제 기능 개발 관련 커밋과 Github Action CI를 수정하는 커밋이 있는데

이는 서로 다른 내러티브 이므로 서로 분리하는 게 좋다.

1. git rebase -i 명령어 실행 후 분리할 commit을 edit(e) 표시
2. 저장 후 닫으면 앞에서 edit로 표시한 커밋 도달 할 때까지 커밋을 적용한다.
3. 원래 커밋은 취소한 다음, 적절한 크기의 커밋을 만든다. `git add -p` + `git commit`
4. 마지막으로 git rebase --continue를 실행한다.

반대로 너무 작은 내러티브들로 커밋이 작성되어 합칠 때도 필요하다.

1. git rebase -i 명령어 실행 후 합치면서 squash(s) 또는 fixup(f) 표시
2. 합칠 때 합쳐질 변경사항의 위치를 조정할 수도 있다.
3. 저장 후 닫으면 커밋 메시지를 새롭게 작성한다.

 

 

두 번째 문제

적당한 크기와 명확한 내러티브의 커밋이라고 해도 작은 변화가 혼란을 줄 수 있다.

코드는 작성자의 생각보다 명확하게 의미를 전달하는 경우가 드물다.

온전하게 변경의 의도를 파악하지 못하면 수정을 버그라고 생각하고, 버그를 기능으로 생각하게 된다.

 

해결방법

이 변경사항이 어떤 동작을 하고 왜 이렇게 수정했는지 커밋 메시지에 설명하시오.

 

커밋 메시지는 독자, 즉 코드를 읽는 사람을 위한 것이므로 독자가 알아야 할 상황을 명확하게 전달해야 한다.

코드 작성자는 개발하면서 알게 된 백그라운드 지식, 컨텍스트가 쌓였지만 읽는 사람은 그렇지 않다. (한 달 지난 나도 포함)

무엇과 왜는 다시 상위 레벨과 하위 레벨로 세분화하여

하나의 커밋메시지가 답해야 할 4가지 질문으로 구성한다.

	무엇을 하는가?	왜 하는가?
상위 레벨 (전략)	의도 (이것은 무엇을 달성하나요?)	컨텍스트 (지금 이 동작을 하는 이유는 무엇인가요?)
하위 레벨 (전술)	구현 (어떤 수정이 있나요?)	정당성 (이 수정이 발생한 이유는 무엇인가요?)

 

리뷰 요청하기 전 4가지 질문에 답할 수 있는 커밋 메시지를 작성하기 위해서 메시지를 수정하는 방법이다.

1. git commit --amend 명령어 실행 후 수정할 커밋 메시지의 상태를 pick에서 reward(r)로 변경
2. 저장 후 닫으면 커밋 수정하는 화면으로 넘어간다.
3. 4가지 질문을 되새기면 답할 수 있는 메시지를 작성한다.
4. 너무 자세히 적으면 그것대로 혼란을 줄 수 있으니 균형을 맞춰 작성한다.

 

더 나은 프로젝트 빌드하기

 

코드 리뷰

앞에서 충분히 잘 작성된 커밋 구성과 메시지를 작성했다면 코드리뷰는 좀 더 수월해진다.

리뷰어는

1. 커밋 메시지와 코드 내용을 가볍게 훑어보면서
2. 하나의 커밋이 한 가지 작업을 수행하는지 완전하지 않은 구현이 있지 않은지 확인
3. 각 커밋을 진지하게 읽으면서 커밋 메시지와 구현이 일치하는지 확인
4. 콘텍스트와 정당성을 이용해 코드를 이해
5. 지금까지 과정을 통해 만들어진 코드 변경사항과 포괄적 내러티브의 멘탈 모델을 이용해 코드 효율성과 버그를 확인

버그 찾기

만약 배포가 계속 실패하고 원인이 어떤 건지 감도 잡을 수 없는 경험을 했다면

git bisect는 유용한 도구다.

정상 커밋과 문제가 되는 커밋을 이진검색으로 찾아준다.

 

한 가지 조건이 있는데 커밋이 충분히 작아야 하는데, 그렇지 않으면 코드 한줄한줄 눈으로 파악해야 한다.

 

근본 원인 분석하기

git bisect로 문제의 원인인 커밋을 찾았지만 커밋이 충분히 작지 않다면 문제원인을 바로 파악하기 어렵다.

이때 필요한 도구가 git blame, git log 명령어다.

 

git blame을 이용하여 특정 코드 영역의 수정이 발생한 커밋들을 찾을 수 있다.

 

git log의 필터 기능을 이용하여 원하는 커밋을 볼 수 있고

git blame과 마찬가지로 변경사항에 대항 멘탈 모델을 구축하는데 도움이 되며

이는 버그의 근본원인을 찾는데 도움이 된다.

 

정리

커밋 개선을 위한 몇 가지 지침을 소개한다.

1. 커밋은 내러티브로 구성한다.
2. 각 커밋은 작고 한 가지 수정만 있어야 한다.
3. 커밋 메시지에는 수정의 "무엇"과 "왜"를 설명해야 한다.

커밋은 프로젝트의 스토리를 전달하며, 이러한 전략은 좋은 커밋을 만드는 데 도움이 될 것이다.

 

---

Git을 단순히 스냅샷을 기록하는 저장소로 생각한다면 커밋 메시지는 test1, test2, test3처럼 쓸 여지가 다분하다.

저장소가 아니라 이 프로젝트를 설명해 주는 재밌는 스토리를 담은 책이라고 생각해 봐야겠다.

 

그러면 자연스럽게 의식이 아래처럼 흐르지 않을까?

스토리는 개연성이 필요하니 작업을 어떤 순서로 진행하고 어떻게 커밋을 구성할지 고민하고

커밋 메시지를 작성할 때는 4가지 질문에 "어느 정도" 답 할 수 있도록 작성한다.

 

물론 너무 작게 나누고 메시지만 왕창 쓰는 것도 좀... 뭐든 균형이 중요하다. ㅎㅎ