3주간의 우아한테크코스 4기 프리코스 과정이 끝났습니다.
프리코스를 진행하며 학습한 내용들을 정리하고,
혹은 놓쳤던 부분에 대해 추가로 공부하여 보완한 내용들을 포스팅해보고자 합니다.
Git의 커밋 단위는 앞 단계에서 README.md 파일에 정리한 기능 목록 단위로 추가한다.
AngularJS Commit Message Conventions 참고해 commit log를 남긴다.
목차
1. 커밋 메시지 컨벤션의 필요성
2. Commit 메시지 포맷
3. 우아한테크코스 커밋 메시지 사례로 살펴보는 Subject line 구성 상세
4. <type>(<scope>)에 올 수 있는 표현들
5. 사례 분석 (1) - 신규 기능 추가 예시
6. 사례 분석 (2) - 오류 수정 예시
7. 사례 분석 (3) - 단순 수정 예시
8. CHANGELOG.md 파일 생성하기 (1) - 간단한 버전
9. CHANGELOG.md 파일 생성하기 (2) - 조금 더 복잡한 버전
1. 커밋 메시지 컨벤션의 필요성
지난 자바 코딩 컨벤션에 이어, 이번에는 커밋 메시지에 대한 컨벤션입니다.
제공된 링크에서는 커밋 메시지 컨벤션의 규칙을 지켜야 하는 이유를 세가지로 이야기합니다.
1. script를 이용한 CHANGLOG.md 파일 자동 생성
2. git bisect 를 이용한 중요하지 않은 커밋 무시
3. 더 나은 이력 정보 제공
당연히 협업을 위해 제대로된 정보를 제공해야 한다는 생각은 해왔습니다.
가령 어느 파일을 어느 목적으로 어떻게 수정했다는 내용을 간략하지만 최대한 담으려 해왔습니다.
그런데 CHANGELOG.md 파일을 스크립트로 자동생성할 수 있다는 내용은 정말 신기했습니다.
그러면 먼저, 어떻게 커밋 메시지를 작성해야할 지 알아보겠습니다.
2. Commit 메시지 포맷
<type>(<scope>): <subject> - Subject line
<BLANK LINE> - 줄 바꿈으로 구분한다
<body> - Message body
<BLANK LINE>
<footer> - Message footer
1. **Subject line**
1. 변경 사항에 대한 간단한 설명.
2. 70자를 넘기지 않도록 한다.
2. **Message body**
1. 수정 이유와 전후 비교 설명.
2. 명령형 현재 시제로 작성한다. (changed X, change O)
3. 70자를 넘기면 줄바꿈한다.
3. **Message footer**
1. 주요 변경사항은 푸터에 변화에 대한 상세설명, 정의, 이전 노트와 함께 명시되어야 한다.
2. 전후를 Before : scope: { ~~ } After : scope: { ~~~ } 와 같이 상세하게 명시한다.
3. 처리 완료된, 즉 close 된 이슈에 대해서는 `Closes #123, #124` 로 표기한다.
3. 70자를 넘기면 줄바꿈한다.
이메일을 생각해보면 쉽습니다.
메일 제목이 맨 위에 나오고, 메일 내용이 나오고, 마지막에 서명(푸터)이 나옵니다.
각각은 줄바꿈으로 구분됩니다.
많은 경우 첫번째 줄에 해당하는 Subject line만 작성되기도 하고,
필요한 경우 Message Body와 Message footer를 사용합니다.
3. 우아한테크코스 커밋 메시지 사례로 살펴보는 Subject line 구성 상세
<type>(<scope>): <subject> - Subject line가장 많이 사용하게 될 Subject line에 대해 보다 자세히 알아보겠습니다.
언제나 학습에서 가장 효과적인건 좋은 모델을 발견하는 것이라고 생각합니다.
그래서 우아한테크코스 모집 과정을 관리하는 공개 레포지토리의 커밋 이력을 확인해봤습니다.
AngularJS Git Commit Message 컨벤션을 완벽히 준수하고 있는 모습으로 생각됩니다.
그럼 위 사례에서 드러난 컨벤션들을 알아보겠습니다.
- 영어로 작성 (우아한테크코스 프리코스에서는 한글 커밋 메시지도 허용했습니다)
- Optional이지만 <scope>를 항상 작성
- 일부 예외를 제외하면 대부분 70자 이내로 Subject line을 작성
- 첫문자를 대문자로 작성하지 않음
- 커밋 메시지 끝에 . 을 사용하지 않음
또한, 주목할만한 컨벤션 중 하나는, 반드시 명령형, 현재 시제로 작성한다는 것입니다.
무엇무엇을 고쳤다 라는 의미로 fixed 로 쓰는 게 아니라 fix 로 작성해야 한다는 의미입니다.
이는 Subject line 뿐만 아니라 Message body와 Message footer에서도 공통으로 적용됩니다.
4. <type>(<scope>)에 올 수 있는 표현들
지금까지 커밋 메시지의 구성과 사례를 살펴봤는데요,
그러면 Subject line의 type과 scope에는 어떤 표현들이 올 수 있는지 살펴보겠습니다.
<type>
feat (feature)
fix (bug fix)
docs (documentation)
style (formatting, missing semi colons, …)
refactor
test (when adding missing tests)
chore (maintain)
<scope>
location, browser, compile, rootScope ...
<type> 자리에는 어떤 유형의 작업을 했는지를 작성합니다.
기능 추가의 feat, 버그 수정의 fix, 문서 추가의 docs 등이 주로 사용됩니다.
<scope> 자리에는 특별히 정해져있기 보다는 프로젝트마다 규약을 정해서 사용하는 것 같습니다.
위에서 살펴본 우아한테크코스 레포지토리에서는 apply scope가 가장 많이 확인되는데요,
이는 우아한테크코스에 지원하는 기능 관련을 의미하는 게 아닐까 생각됩니다.
위 커밋 메시지는 제가 실제 우아한테크코스 제출용으로 작성했던 커밋 메시지입니다.
scope를 명시하지 않은 점, add test, add function 과 같은 접두어로 인해 가독성이 떨어지는 점이 아쉽네요.
이후 커밋 메시지에서는 scope를 꼭 명시하고, 상투적 표현을 줄이도록 해봐야겠습니다.
5. 사례 분석 (1) - 신규 기능 추가 예시
AngularJS Git Commit Message 문서에 예시로 나와있는 사례를 살펴보며
커밋 메시지 컨벤션에 대해 좀 더 익숙해져보도록 하겠습니다.
먼저 신규 기능 추가 예시입니다.
feat($browser): onUrlChange event (popstate/hashchange/polling)
Added new event to $browser:
- forward popstate event if available
- forward hashchange event if popstate not available
- do polling when neither popstate nor hashchange available
Breaks $browser.onHashChange, which was removed (use onUrlChange instead)Subject line을 보면, type과 scope를 통해 browser 관련 기능 추가임을 알 수 있습니다.
onUrlChange event 라는 기능이 추가된 것 같네요.
Message body 에서는 Subject line과 달리 첫 문자가 대문자인 것이 보입니다.
그리고 추가기능에 대한 상세 내역이 작성되었고요.
Message footer에서는 Breaks 라는 접두어를 통해 제거된 기능과 대체로 사용할 기능이 명시되었습니다.
6. 사례 분석 (2) - 오류 수정 예시
fix($compile): couple of unit tests for IE9
Older IEs serialize html uppercased, but IE9 does not...
Would be better to expect case insensitive, unfortunately jasmine does
not allow to user regexps for throw expectations.
Closes #392
Breaks foo.bar api, foo.baz should be used instead다음으로 오류 수정 예시입니다.
compile 범위에 영향을 미치는 fix 수정이 있었음을 알 수 있고요,
익스플로러 9버전에 대한 몇몇 단위 테스트가 수정된 것 같습니다.
Message body에는 해당 수정이 필요했던 이유가 명시되어 있고,
Message footer 에서는 Closes #{이슈 넘버}를 통해,
해당 커밋을 통해 어떤 이슈가 종결되었는지를 나타냅니다.
추가적으로 foo.bar 라는 api가 더이상 사용 불가해졌고 foo.baz를 사용하라고 안내되어 있네요.
7. 사례 분석 (3) - 단순 수정 예시
style($location): add couple of missing semi colonsstyle 로 시작하니 포맷팅에 대한 단순 수정일거라 예상됩니다.
몇몇 누락된 세미콜론을 추가했다는 내용입니다.
추가적 설명이 불필요할 경우 Message body나 Message footer가 생략되었음을 알 수 있습니다.
8. CHANGELOG.md 파일 생성하기 (1) - 간단한 버전
지금까지 커밋 로그를 어떻게 남겨야하는지 규약에 대해 알아봤습니다.
그러면 이제 스크립트를 이용해 CHANGELOG.md 파일을 자동으로 생성해보겠습니다.
시작점은 바로 git log 명령어 입니다.
아래 사례는 제가 실제 우아한테크코스 4기 프리코스에 제출했던 커밋 로그입니다.
git log 명령어는 커밋 히스토리를 조회하는 git 내장 명령어입니다.
git log 명령어에 대한 자세한 설명은 공식 문서 링크에서 확인하실 수 있습니다.
아무 파라미터 없이 사용했을 때, 위 그림과 같이
커밋 아이디, 작성자, 날짜, 그리고 커밋 메시지가 순차적으로 나열됨을 볼 수 있습니다.
우선 아주 간단한 버전의 CHANGELOG.md 파일을 만들어 보겠습니다.
git log --pretty="- %s" > CHANGELOG.md
- fix: add utf-8 encoding option to build.gradle
- test: add test for judging by user input
- style: add new line at the end of QuizMakerTest.java
- test: add test for creating new quiz
- refactor: change class name AnswerBall to Answer
- feat: compose features
- feat: add function to repeat or not when it is finished
- feat: add function to print result of user input
- refactor: add vo classes to hand values over
- feat: add function to check if user input is correct
- feat: add function to read and validate user input
- feat: add function to create a quiz
- docs: add function list to implement
- feat: setup baseball game project
%s 는 요약을 의미합니다. > CHANGELOG.md 부분은 파일로 출력을 의미합니다.
이렇게 해서 아주 간단한 CHANGELOG.md 파일을 자동으로 생성해보았습니다.
다음으로는 조금 더 가독성 좋게 꾸며보겠습니다.
9. CHANGELOG.md 파일 생성하기 (2) - 조금 더 복잡한 버전
저는 이번 포스팅에서 generate-changelog 라는 노드 모듈을 사용하였습니다.
Github Changelog Generator, Git Chglog, Auto Changelog, Conventional Changelog 등
다양한 모듈이 있으므로 필요에 따라 찾아보시길 바랍니다.
1) node를 설치합니다.
2) generate-changelog 를 취향에 맞게 설치합니다.
$ npm i generate-changelog -D # install it as a dev dependency
# OR
$ npm i generate-changelog -g # install it globally3) 프로젝트 루트 경로에 package.json 파일을 만들고 안에 {} 를 입력합니다.
4) changelog generate 명령어로 CHANGELOG.md 파일을 생성합니다.
+ CategoryInfo : 보안 오류: (:) [], PSSecurityException
+ FullyQualifiedErrorId : UnauthorizedAccess
changelog generate 명령어가 위와 같은 오류를 반환할 경우 대응방법입니다.
1. Power Shell 을 관리자 권한으로 실행
2. Set-ExecutionPolicy RemoteSigned
3. Y
4. changelog generate 를 다시 시도
5. Set-ExecutionPolicy Restricted
6. Y
5) 결과를 확인합니다.
#### 2021-12-16
##### Documentation Changes
* add function list to implement (896689e2)
##### New Features
* **gradle:** integrate gradle, editorconfig, checkstyle (a7660cb5)
* compose features (83889819)
* add function to repeat or not when it is finished (8efc4bad)
* add function to print result of user input (cca0c362)
* add function to check if user input is correct (7102b95b)
* add function to read and validate user input (fa9f2184)
* add function to create a quiz (85bdfaf4)
* setup baseball game project (94764a7a)
##### Bug Fixes
* add utf-8 encoding option to build.gradle (da9ec1cb)
##### Refactors
* change class name AnswerBall to Answer (faeec9a3)
* add vo classes to hand values over (27ccee91)
##### Code Style Changes
* **text:** reformat files crlf > lf and 4 spaces > tab (537fe7f4)
* **checkstyle:** add checkstyle rule and fomatter file (8e41cd23)
* **editorconfig:** add .editorconfig configuration file (fe7a2603)
* add new line at the end of QuizMakerTest.java (d7806902)
##### Tests
* add test for judging by user input (d4d9e511)
* add test for creating new quiz (18db30e6)
10. 소감
커밋 메시지를 어떻게 남겨야 하는지에 대해 간단한 고민은 있었지만,
이번 과정을 통해 정확한 커밋 메시지 컨벤션이 어떻게 구성되는지,
그리고 왜 그렇게 작성해야하는지에 대해 알 수 있었습니다.
CHANGELOG.md 파일을 자동 생성하는 과정을 통해
프로젝트가 체계적으로 관리될 수 있음에 많이 놀랍고 신기했습니다.
최근 사내 형상관리를 SVN에서 Gitlab으로 옮겨가는 추세인데,
제가 처음부터 구성하는 프로젝트가 있어서 여기에 먼저 커밋 메시지와 CHANGELOG를 적용해보고자 합니다.
출처
https://github.com/woowacourse/java-baseball-precourse
GitHub - woowacourse/java-baseball-precourse: 숫자 야구게임 미션을 진행하는 저장소
숫자 야구게임 미션을 진행하는 저장소. Contribute to woowacourse/java-baseball-precourse development by creating an account on GitHub.
github.com
https://gist.github.com/stephenparish/9941e89d80e2bc58a153
AngularJS Git Commit Message Conventions
AngularJS Git Commit Message Conventions. GitHub Gist: instantly share code, notes, and snippets.
gist.github.com
How To Automatically Generate A Helpful Changelog From Your Git Commit Messages - Michael Hoffmann (Mokkapps) - Senior Frontend
Creating a changelog is a usual task if a new software version is going to be released. It contains all the changes which were made since…
www.mokkapps.de
A Beginner’s Guide to Git — What is a Changelog and How to Generate it
Say you are a developer, and you use Git for one of your projects. You want to share the changes you made with your users, but you don’t know how. Well, then this article is for you. In the last part of this series, I shared with you how
www.freecodecamp.org
'우아한테크코스 4기' 카테고리의 다른 글
| 우아한테크코스 웹 백엔드 4기, 화음을 좋아하는 리차드 (0) | 2022.01.20 |
|---|---|
| 우아한테크코스 4기 프리코스 후기 (4) - README.md 작성 (markdown) (0) | 2021.12.17 |
| 우아한테크코스 4기 프리코스 후기 (3) - Github, Git, 과제제출방법 (0) | 2021.12.17 |
| 우아한테크코스 4기 프리코스 후기 (1) - 자바 코딩 컨벤션 (0) | 2021.12.16 |
| 우아한 테크캠프 Pro ! 선 지원 후 고민! (0) | 2021.09.14 |
