초보 개발자를 위한 커밋 메시지 작성법과 규칙

1. 커밋 메시지 작성의 중요성

 

 

 

커밋 메시지는 소프트웨어 개발에서 매우 중요한 역할을 합니다. 개발자들은 코드를 작성하고 수정할 때마다 커밋을 해야합니다. 이때 커밋 메시지에는 이전 커밋과의 차이점, 수정한 이유, 추가된 기능 등 코드 변경사항을 요약하는 내용이 들어가야합니다.

 

커밋 메시지를 제대로 작성하는 것은 추후 코드 변경사항에 대한 이력을 추적할 때 도움이 됩니다. 또한, 커밋 메시지를 작성함으로써 개발자들 간의 소통이 원활해지고 프로젝트 히스토리를 파악하는 데 도움이 됩니다.

 

따라서, 모든 개발자들은 커밋 메시지 작성에 신경을 써야하며, 더 나은 커밋 메시지 작성을 위해 규칙을 만들어야 합니다. 커밋 메시지 작성규칙을 준수하면 팀원들이 더 쉽게 코드 변경 이력을 파악할 수 있습니다.

 

 

 

2. 커밋 메시지 규칙

 

 

 

커밋 메시지는 다음과 같은 규칙을 따라 작성해야 합니다.

 

1) 제목과 본문을 한 줄 띄워 분리하기

 

2) 제목은 영문 기준 50자 이내로 작성하기

 

3) 제목은 명령조로 작성하기 (ex. Add, Update, Fix 등)

 

4) 본문은 영문 기준 72자마다 줄 바꾸기

 

5) 본문은 어떻게 변경했는지 보다는 변경한 이유와 구체적인 내용을 작성하기

 

6) 다른 이용자들이 커밋 메시지를 이해할 수 있도록 작성하기

 

이러한 규칙을 따라 적절하고 명확한 커밋 메시지를 작성하면, 협업을 하는 동안 코드 리뷰와 같은 작업에서 다른 개발자와의 소통이 원활하게 이루어질 수 있습니다. 또한, 나중에 프로젝트를 유지보수하거나 버그를 수정해야 할 때도 커밋 메시지를 확인하여 해당 기능이나 코드의 변경 내용을 파악할 수 있습니다.

 

 

 

1) 제목/내용 구분

 

 

 

제목과 내용을 구분해 작성하는 것이 좋습니다. 제목은 가능한 간결하고 명확하게 작성하며, 내용은 자세하게 작성합니다. 긴 커밋 메시지일 경우에는 제목을 요약하고 내용에 자세한 설명을 담아 작성하는 것도 좋은 방법입니다.

 

 

 

2) 간결하고 명확한 제목 작성

 

 

 

커밋 메시지의 제목은 가능한 한 간결하면서도 명확하게 작성해야 해. 제목에는 커밋 변경 내용의 핵심을 담아내야 하며, 다른 사람들도 이해할 수 있도록 작성해야 해. 제목으로 커밋 내용을 완전히 설명하지는 않지만, 전체 커밋 메시지를 대표하는 단어나 문구를 선택하면 좋아.

 

예시)

 

- 올바른 제목: "버그 수정 - 로그인 페이지에서 오류 해결"

 

- 부적절한 제목: "작업 완료"

 

버그 수정에 대한 정보는 제목에서 명확하게 드러나야 해. "작업 완료"와 같은 불분명한 제목은 전체 커밋 메시지를 이해하기 힘들게 만들기 때문에 피해야 해.

 

 

 

3) 자세하면서도 간결한 내용 작성

 

 

 

커밋 메시지의 내용은 자세하고 명확해야 한다. 하지만 그래도 간결한 내용으로 작성해야 한다. 이를 위해서는 다음과 같은 팁을 활용할 수 있다.

 

- 첫 번째 줄에는 간결하게 변경 내용을 요약해준다. 예를 들어 "버그 수정"보다는 "로그인 오류 수정"과 같이 구체적으로 작성하는 것이 좋다.

 

- 두 번째 줄은 선택적으로 사용할 수 있으며 변경 이유나 상세 내용을 덧붙일 수 있다.

 

- 세 번째 줄 이후에는 간단한 내용 설명을 작성한다. 이 때 명령어형이 아닌 일반 문장으로 작성하는 것이 좋다. 또한 동사 원형으로 시작하는 것도 좋은 습관이다. 예를 들어 "로그인 오류 수정" 대신 "로그인 오류를 수정했습니다"와 같이 작성할 수 있다.

 

- 오타나 잘못된 링크 등 오판을 방지하기 위해 내용을 미리 확인하는 것도 중요하다.

 

커밋 메시지 작성의 지침으로는 "어떻게 커밋했는지를 이해할 수 있도록 작성하라"는 것이 있다. 이를 준수하면서 자세하면서도 간결한 내용으로 작성하는 것이 좋다.

 

 

 

4) 오타와 문법적 오류에 주의

 

 

커밋 메시지는 코드와 함께 저장소 내 역사를 기록하는 용도로 사용되며, 오류가 있을 경우 나중에 코드를 추적하거나 수정할 때 문제가 발생할 수 있습니다. 따라서 올바른 문법과 철저한 검수 과정을 통해 오타나 문법적 오류를 방지해야 합니다.

 

커밋 메시지는 오타가 없도록 꼼꼼히 검수해야 합니다. 커밋 메시지에 오타가 있다면, 나중에 코드를 이해하거나 수정할 때 혼란스러워질 수 있습니다. 또한 문법적인 오류가 있는 경우에도 마찬가지입니다. 커밋 메시지도 완벽한 문장으로 작성하는 것이 좋습니다.

 

이를 방지하기 위해서는 코드를 작성하고 커밋 메시지를 작성할 때 모두 집중해야 합니다. 또한, 커밋 메시지에 대해 다른 개발자나 코드 리뷰어에게 검수를 받는 것도 좋은 방법입니다. 이를 통해 보다 완벽한 코드 작성과 검수를 할 수 있습니다.

 

 

 

5) 이슈 트래커와 연동하기

 

 

 

커밋 메시지에는 이슈번호를 포함시키는 것이 좋습니다. 이슈번호가 있으면 어떤 이슈에 대한 변경사항인지 쉽게 파악할 수 있기 때문입니다.

 

예시) [이슈번호] Fix typo in README.md

 

따라서 이슈 트래커와 연동하여 커밋 메시지에 이슈번호를 자동으로 추가하는 기능을 사용하면 편리합니다. 이를 위해서는 이슈 트래커에서 제공하는 다양한 툴을 사용할 수 있습니다. 예를 들어, GitHub에서는 커밋 메시지에 #이슈번호를 포함시키면 해당 이슈와 자동으로 연동됩니다.

 

예시) Fix typo in README.md #12

 

위와 같이 작성하면 12번 이슈와 이 커밋이 자동으로 연동됩니다. 이렇게 연동되면 해당 이슈 페이지에서 어떤 커밋이 관련된 것인지 확인할 수 있습니다. 이를 통해 쉽게 변경 사항을 찾아 볼 수 있고, 이슈에 대한 처리 상황을 파악할 수 있습니다.

 

 

 

3. 좋은 커밋 메시지 예시

 

 

 

- Fix typo in README.md

 

- README.md 파일에서 오타를 수정했다는 커밋 메시지입니다. 간단하고 명확하게 수정한 내용을 전달하고 있습니다.

 

- Add login form validation feature

 

- 로그인 폼 유효성 검사 기능을 추가했다는 커밋 메시지입니다. 커밋한 내용이 어떤 것인지 명확히 설명하고 있습니다.

 

- Refactor user controller code

 

- 사용자 컨트롤러 코드를 리팩토링했다는 커밋 메시지입니다. 수정한 내용을 구체적으로 설명하지는 않았지만, 큰 틀에서 코드를 개선했다는 것을 전달하고 있습니다.

 

- Implement new feature to upload profile picture

 

- 프로필 사진 업로드 기능을 추가했다는 커밋 메시지입니다. 새로운 기능을 구현했다는 것을 명확하게 전달하고 있습니다.

 

- Update dependencies to fix security vulnerability

 

- 보안 취약점을 해결하기 위해 의존성을 업데이트했다는 커밋 메시지입니다. 내부적으로 보안에서 중요한 업데이트를 진행했음을 명확히 전달하고 있습니다.

 

위의 예시처럼 좋은 커밋 메시지는 가독성이 좋고 명확하게 커밋한 내용을 설명하는 것이 필요합니다. 이러한 규칙을 지켜가며 작성하면, 다른 개발자들이 협업하는데 큰 도움이 될 수 있습니다.

 

 

 

4. 나쁜 커밋 메시지 예시

 

 

 

① "수정함"

 

- 무엇을 수정했는지 알 수 없고, 너무 간단한 내용이기 때문에 나중에 커밋 내용을 찾을 때 찾기 어렵습니다.

 

② "이전 버전으로 롤백"

 

- 이전 버전에서 무엇을 수정했는지 알 수 없습니다. 롤백한 이유와 함께 무엇을 수정했는지 상세히 작성하는 것이 좋습니다.

 

③ "오타 수정"

 

- 수정한 파일 이름, 위치, 수정한 단어 등 구체적인 내용을 작성하는 것이 좋습니다.

 

④ "작은 수정"

 

- 작은 수정이라도 이 내용이 어떤 수정인지 알려줘야 합니다.

 

⑤ "수정 완료"

 

- 앞으로 무엇이 바뀌었는지 알 수 없습니다. 구체적으로 무엇이 변경되었고, 그 변경 내용이 어떻게 적용되는지 작성해주세요.

 

 

 

5. 커밋 메시지 작성 시 고려해볼 점

 

 

 

5. 커밋 메시지 작성 시 고려해볼 점:

 

1) 명확한 제목 작성: 제목은 커밋의 주요 변경 사항을 요약해야 한다. 되도록이면 50자 내외로 작성하며, 영문으로 작성한다.

 

Good Example: "Add feature for user authentication"

 

Bad Example: "New update"

 

2) 상세한 내용 작성: 제목만으로는 부족한 정보를 보충해 줄 수 있는 내용을 작성한다. 상세한 변경점, 변경 사항의 이유나 수정된 이슈 등을 작성한다.

 

Good Example: "Add feature for user authentication by setting up a password reset function using Django"s built-in authentication system and configuring email settings."

 

Bad Example: "Update code"

 

3) 현재 시제 사용: 커밋 메시지는 현재 시제로 작성한다.

 

Good Example: "Fix typo in login page"

 

Bad Example: "Fixed typo in login page" (과거형 사용)

 

4) 커밋 범위 제한: 한 커밋에서 여러가지 변경 사항이 있으면, 가능한 범위를 제한해 각각의 커밋으로 나눈다.

 

Good Example: "Add authentication feature for user login"

 

Bad Example: "Add authentication feature for user login and fix small bug in registration page"

 

5) 적절한 해결 방법 기술: 문제를 해결한 방식을 작성한다.

 

Good Example: "Fix bug in registration page by adding validation check for email field"

 

Bad Example: "Fix bug in registration page"

 

6) 참고자료 기록: 참고한 자료(웹사이트, 블로그, 문서 등)를 작성한 후, 출처를 표기한다.

 

Good Example: "Add feature for user authentication by referring to Django official documentation on authentication"

 

Bad Example: "Add feature for user authentication" (자료 출처 기록 없음)