Conventional Commits and commitlint - 관례적인 커밋 메세지와 이를 돕는 commitlint

hyperskill - Conventional Commits and commitlint 영어 원문

개발 팀들은 그들의 프로젝트에서 작업 할 때 Git 버전 컨트롤 시스템을 자주 사용합니다.

그러므로, 당신이 또 다른 것과 혼동하지 않도록 특정한 관례를 인지하고 따르는 것이 중요합니다.

이러한 관례 중 하나는 commit 메세지를 어떻게 작성하는가에 초점이 맞춰져 있습니다.

결국, 이 관례는 누군가 그들의 동료에게 코드에서 만들어 진 변경사항에 대해서 말하는 법입니다.

또다른 관례 중 하나는 전통적인 commit 사양입니다.

이 관례에 기초하여, commit 들은 짧으며, 만들어 진 변경사항에 대한 유용한 정보를 담고 있습니다.

이번 주제에서는, 우리는 관례적(컨벤션) commit 사양에 따라 commit 메세지를 작성하는 올바른 방식을 배웁니다.

회사마다 각각의 commit 메세징 규칙을 가지고 있을 거라는 것을 기억하세요.

이번 주제에서는, 몇 가지 일반적으로 받아들여지는 추천 방식에 대해서만 배울 겁니다.

Conventional Commits specification - 컨벤션 커밋 사양

---

Conventional Commits 이 사이트는 커밋 메세지를 만드는 과정의 표준입니다.

이는 개발자들에게 커밋을 더 쉽게 만들게 해줄 뿐만 아니라,

써드 파티 기여자들이 코드가 변경되었음을 가르키게 해 줍니다.

이 Conventional Commit 은 명백한 commit 기록을 위한 가이드라인의 집합을 직관적으로 제안합니다.

The Angular Commit Guidelines 이는 전통적인 commit 상세의 기초이며, 영감의 주요 원친이 되었습니다.

게다가 사실은 이러한 사양은 개발자들에게 더 가독성 좋은 메세지를 만들어 주며,

또한 그 위에 도구를 자동화시켜 간단히 작성 합니다.

예를 들어, 변경기록을 자동으로 생성하는 도구를 만들거나, 메세지에 기반하여 몇 가지를 분석합니다.

이러한 컨벤션의 마지막 버전은 1.0.0 이며, 모든 고유한 프로퍼티는 여기서 멘션되며, 이 버전과 관련되어있습니다.

Commit message structure - 커밋 메세지 구조

---

어느 규칙처럼, 컨벤션 커밋 사양은 스스로의 구조를 가지고 있습니다.

커밋 메세지를 작성하는 데 일반적으로 받아들여지는 스타일은 밑의 구조를 따르고 있습니다 :

<type>[(scope)][!]: <description>

[body]

[footer]

1. Type :

커밋에 많은 타입이 있지만, 메인 타입은 feat와 fix입니다.

그 외에도, build, chore, docs 그리고 또 다른 것들도 존재합니다.

주요하지 않은 타입은 조금 나중에 각각에 대해 배우게 됩니다.

2. Scope (optional) :

Scope는 이 커밋에서 만들어지는 변경사항으로 인해 영향을 받는 문서 혹은 코드의 부분을 설명합니다.

예를 들어 : api, parser, 등등이 있습니다.

괄호를 가르킵니다.

당신은 ,, /, \를 사용하여 여러 개의 스코프를 식별 할 수 있습니다.

3. Exclamation mark (optional) :

! (exclamation mark) 는 커밋의 중요성을 강조합니다.

당신은 BREAKING CHANGE 를 밑에 포함해야 합니다.

이는 커밋에서 만들어진 변경사항의 중요성을 설명합니다.

4. Description :

이 부분은 만들어진 변경사항에 대해 짧은 설명을 포함하고 있습니다.

설명의 길이는 주로 하나의 간단한 문단 정도입니다.

5. Body (optional)

이 부분에서는, 변경 사항이 더 자세히 설명됩니다.

두 개 정도의 작은 단락을 작성하는 것이 허용됩니다.

6. Footer (optional)

말 그대로, 전에 말했듯이 BREAKING CHANGE 를 포함합니다.

이 footer는 만들어 졌던 중요한 변경사항을 설명합니다.

어떤 변화는 어플리케이션의 아키텍쳐에 중요하게 영향을 미치며,

어떤 변화는 중요한 사안으로 고려되어야 합니다.

각각의 footer는 단어 토큰으로 시작되어야 하며, :<space> 혹은 <space># 분리자를 따라야 합니다.

그리고 나서 string 밸류로 끝납니다.

이러한 것은 git trailer convention에 영감을 받았으며, 비슷한 구조를 제공합니다.

이제 몇 가지 예제를 보겠습니다.

가장 짧은 커밋 메세지는 이와 같이 보일 겁니다 :

fix: /users api endpoint error fix

여기 또 다른 커밋 메세지가 있는데, 이 메세지는 변경사항이 만들어진 scope를 설명하고 있습니다.

feat(api): add /documents endpoint

BEAKING CHANGE footer를 가지고 있는 중요한 커밋에 대한 예제입니다 :

chore!: drop support for Node 6

BREAKING CHANGE: use JavaScript features not available in Node 6.

이제 주요 커밋 타입에 대해 빠르게 봐 봅시다 :

Commit types - 커밋 타입

---

컨벤션 커밋 사양에 따라, 커밋에 두 개의 주요 타입이 있습니다. :

1. feat (Feature) - 어플리케이션이 새로운 기능을 얻었을 때 사용합니다.
2. fix (Fix) - 기능을 변경하지 않고, 이미 존재하고 있는 어플리케이션의 부분에 있는 에러를 고친 commit
   에 의해 변경되었을 때 사용합니다.

하지만, 가끔 이 두 개의 타입으로는 우리가 만든 변경사항을 커버하기에 충분치 않습니다.

따라서, 커뮤니티에서 사용되는 또다른 타입 또한 있으며, 문법 도구에 의해 지원됩니다.

1. build (Build) - 빌드 시스템에서 변경 사항을 만드는 데 사용하거나, 어플리케이션이 작동하기 위해 필요 한 전역적 디펜덴시(의존성) 에 사용합니다.

2. chore (Chores) - 변경 사항이 어플리케이션의 운영에 관련이 없을 때 사용합니다.

3. CI (Continuous Integrations) - 지속적인 통합 구성(continuous integration configuration) 이 바뀔 때 사용합니다.

4. docs (Documentation) - 문서를 바꿀 때 사용합니다. 잘못 작성한 글을 수정하거나, 언어를 추가하거나 등등..

5. perf (Performance) - 앱에 있어 성능을 향상시키는 변경사항을 만들었을 때 사용합니다.

6. refector (Refactoring) - 기능성에는 영향을 미치지 않지만, 코드의 구조에 변화를 일으킬 때 사용합니다.

7. revert (Reverts) - 실수, 혹은 몇 가지 위반으로 인해 이전의 변경사항이 들어있는 commit을 사용 할 때 사용합니다.

8. style (Style) - 코드의 스타일에 변경이 있을 때 사용합니다. 구조는 변경하지 않구요.

9. **test (Testing) - 새로운 테스트들을 추가하거나, 낡은 테스트들을 바꾸는 것과 같이 테스팅 시스템을 변경 할 때 사용합니다.

이건 아마 많다고 느껴질 겁니다.

하지만, 이 모든 타입들을 연습으로 사용함으로서, 당신은 이들을 더 쉽게 기억 할 것이며, 이들을 가이드로서 작동 될 겁니다.

다음 섹션에서는, 명령어 라인 플러그인을 보게 될 건데, 이는 당신이 커밋 메세지를 작성하는 것을 돕습니다.

Commitlint - 커밋 메세지 문법 도구

---

Commitlint는 커밋 메세지들을 나열하기 위한 간단한 도구입니다.

이는 당신의 메세지들이 규칙 집합을 준수하는지 확인하고, 오류 변경을 제안합니다.

Commitlint 오피셜 사이트 를 방문하여 이 도구의 가이드라인을 찾을 수 있고, 설치 지침을 찾을 수 있습니다.

Commitlint는 Node Package Manager (NPM) 에 의해 설치 될 수도 있습니다 :

npm install @commitlint/cli @commitlint/config-conventional

그리고 나서 당신은 commitlint.config.js 파일을 프로젝트에 생성해야 하며,

밑의 라인들을 파일에 추가해야 합니다 :

module.exports = {
    extends: [
        "@commitlint/config-conventional"
    ],
}

이는 유틸리티가 당신이 컨벤션 커밋 구성을 확실히 보게 해 줍니다.

그리고 나서 당신은 husky를 설치해야 하며,

husky의 훅들을 가동시켜 당신이 커밋을 만드는 동안 commitlint가 구동 할 수 있게 해 줍니다.

npm install husky
npx husky install

그리고 마지막 단계로 - commit이 완료되기 전에 commitlint를 구동시켜 pre-commit을 추가해야 합니다.

npx husky add .husky/commit-msg "npx --no -- commitlint --edit $1"

위의 단계가 완료되고, 당신은 commitlint를 사용 할 수 있습니다!

이제 commitlint가 어떻게 작동되는지 보기 위해, 반대로 관례적이지 않은 커밋을 만들어 봅시다!

그리고 commitlint가 어떻게 이들에 반응하는지도 봅시다!

git commit -m "abc: unconventional commit message"

husky > commit-msg (node v10.1.0)
No staged files match any of provided globs. # 제공 된 glob 에서 어떠한 것도 staged files와 매칭되는 것이 없습니다.
⧗   input: abc: unconventional commit message   # input: abc: 관례적이지 않은 커밋 메세지입니다.
✖   type must be one of [build, chore, ci, docs, feat, fix, perf, refactor, revert, style, test] [type-enum]    # 입력 된 타입은 앞에 제시 된 타입 중 하나여야 합니다.

✖   found 1 problems, 0 warnings    # 1개의 문제를 찾았고, 0개의 경고가 있습니다.
ⓘ   Get help: https://github.com/conventional-changelog/commitlint/#what-is-commitlint     # 해당 사이트에 들어가 도움을 얻을 수 있습니다.

husky > commit-msg hook failed (add --no-verify to bypass)    # husky를 통한 hook은 실패했습니다. (검증되지 않은 우회로를 추가하세요)

당신이 보다시피, commitlint는 실수에 대해 경고하며, commit를 실행 할 수 없게 합니다.

이러한 것이, commit이 완료되기 전에 commitlint를 구동해야 하는 이유가 됩니다.

만약 당신이 올바른 메세지를 만들었다면 :

git commit -m "feat: login page add"

이 커밋은 성공적으로 작동합니다.

Conclusion - 결론

---

이번 주제에서는, 우리는 커밋 메세지가 규칙을 가지고 있다는 것을 논의했습니다.

이러한 규칙은 Conventional Commits 라고 불리는 당신이 따라야 할 규칙입니다.

당신은 메세지를 작성하는 구조, 커밋의 타입들에 익숙해 졌습니다.

또한, 당신은 Commitlint에 정통하게 되었습니다.

• 당신이 커밋 메세지들을 작성 하는 데 돕는 유용 한 도구입니다.

이 정보는 당신에게 유용 할 것이며,

당신이 큰 회사에서 거대한 프로젝트를 작업하지 않을 때에도 이 규칙을 따를 수 있습니다.

words to remember

---

frequently : 자주

conventions : 컨벤션, 협약, 관례

conventional : 전통적인, 인습적인, 틀에 박힌

observe : 인지하다, 관찰하다

After all : 결국, 아무튼, 하지만

peculiar : 이상한, 독특한, 묘한, 사유 재산, 특수 지역

Exclamation : 감탄, 외침

Exclamation mark : 느낌표

paragraphs : 단락, 절, 구절

comply : 응하다

obey : 순종하다, ~에 복종하다, 명령대로 복종하다

acquainted : 정통한, 사귀게 된, 안면이 있는