본문 바로가기

테크니컬 라이팅

[마소 V.396 리뷰] 영어로 커밋 메시지 쓰기 어렵지 않아요

반응형

커밋 메시지를 그렇게 주의 깊게 보는 개발자들이 있을까 싶고, 당장 나에게 급한 일은 아니라서 이 글은 그냥 넘어갈까 했는데 뒷부분에 JIRA 제목과 내용을 작성하는 가이드가 있더군요. 예전부터 고민하던 내용이라, 이 부분은 정독(?)을 했습니다.

지라 티켓은 제목(필드명: 요약)만 봐도 무슨 내용인지 혹은 무엇을 하겠다는 것인지 알 수 있도록 작성해야 한다.

사실 다들 알지만, 쉽지 않은 일입니다. 검색 기능을 사용해서 내용 검색이 가능하지만, 내용까지 검색하게 되면 불필요한 내용들도 나와서 제목에 딱 요구사항이 드러나는 것이 가장 좋다는 생각입니다만, 그걸 제목에 담아내는 것이 쉽지 않습니다. 그래서 이러이러해야 한다라고 이야기하는 것은 쉽지만, 어떻게 해야 하는 거야~라는 정답을 알려주는 것은 쉽지 않습니다.

필자의 가이드(라인에서는) 태스크와 버그를 구분해서 작업을 한다고 합니다. 태스크인 경우에는 동사로 시작하는 문장을 사용합니다. 이 태스크가 가지고 잇는 실제 작업을 동사 중에서 선택하는 것이죠.

예문 중 'set'으로 시작하는 C항목은 커밋 전에는 추가할 수 있는 친구 수에 제한이 없었는데, 이번에 제한을 구현한 것으로 이해할 수 있다. 반면, D항목과 E항목의 'change'나 'increase'는 태스크를 수행하기 이전에 제한이 존재했다는 것을 피력한다. 이와 같이 드러내고자 하는 의미와 가까운 동사를 선택하면 티켓을 클릭해 상세 페이지를 확인하지 않아도 제목만 보고도 대략 어떤 내용인지 가늠할 수 있는 효과를 얻을 수 있다.

버그 타입의 경우에는 현상을 적으라고 권장합니다. 

버그 타입 티켓은 버그로 인한 현상을 제목으로 쓰도록 한다. 꼭 물리적으로 눈에 보이는 현상이 아니더라도 버그라고 판단하게 한 현상을 적으면 된다. 프로그램을 실행시켰는데 아무 창이 나타나지 않는다든지, 데이터베이스에 테이블을 생성했는데 조회해보니 생성한 테이블이 없다든지, 혹 누군가 만든 모듈을 빌드했는데 이유 없이 런타임 에러가 발생한다든지 등 문제가 되는 현상을 제목으로 작성한다.

버그 타입의 제목은 무엇을 나타내는 명사 또는 동명사가 중요하며 때문에 명사가 먼저 나오게 된다고 합니다.

 

커밋과 관련해서는 해외에서도 많은 글을 찾아볼 수 있는데 요구사항 제목은 잘 설명된 글이 없더군요. 그나마 비슷한 글이 아래 링크 정도입니다. 이 글 역시 태스크와 버그를 구분하고 있으며 제목을 보고 작업을 판단할 수 있게 좀 더 디테일한 분류를 제시하고 있습니다.

https://stratejos.ai/blog/naming-task-bug-user-story-titles/

 

Naming Guide for Task, Bug & User Story Titles - stratejos blog

Naming your task, bug and user story titles has more impact than you might think. Here is a list of common formats for naming your tasks.

stratejos.ai

JIRA에서도 각 제목 구분을 이런 경우에 쓰라고 간단한 가이드는 제공하고 있습니다. 

https://confluence.atlassian.com/adminjiracloud/issue-types-844500742.html

 

Issue types - Atlassian Documentation

 

confluence.atlassian.com

 

 

 

728x90