이 글은 AngularJS commit conventions에 대한 번역 글입니다.
이 규칙은 "the AngularJS commit conventions"으로 채택되었다.
목차
목표
- 스크립트로 CHANGELOG.md 생성을 허용한다
- git bisect에 의한 커밋을 무시해도 된다
- 기록을 찾을 때 더 나은 정보를 제공해야한다
CHANGELOG.md 생성
changelog에서 세 가지 섹션(새로운 기능, 버그 수정, 주요 변경 사항)을 사용한다.
이 리스트는 릴리즈할 때 스크립트에 의해 관련 커밋에 대한 링크와 함께 생성될 수 있다.
물론 실제 릴리즈 전에 이 변경 로그를 편집할 수 있지만, 미리 뼈대를 만들어 둘 수 있다.
마지막 릴리즈 이후 모든 제목(커밋 메시지의 첫번째 줄) 리스트 보기:
git log <last tag> HEAD --pretty=format:%s
현재 릴리즈의 새로운 기능 보기:
git log <last release> HEAD --grep feature
중요하지 않은 커밋 인식
중요하지 않은 커밋은 형식 변경(추가/빈칸 삭제/빈 줄/들여쓰기), 세미콜론 누락, 주석 등이 있다.
따라서 변경점을 찾을 때, 이런 커밋은 무시할 수 있다. (논리적인 변경점이 없는 커밋들)
git bisect을 이용할 때 다음처럼 무시할 수 있음:
git bisect skip $(git rev-list --grep irrelevant <good place> HEAD)
기록 검색 시 추가 정보 제공
이것은 일종의 "문맥" 정보를 추가한다.
다음은 angular의 최근 커밋이다.
- Fix small typo in docs widget (tutorial instructions)
- Fix test for scenario.Application - should remove old iframe
- docs - various doc fixes
- docs - stripping extra new lines
- Replaced double line break with single when text is fetched from Google
- Added support for properties in documentation
커밋들을 보면 모든 메시지가 어떤 것이 변경되었는지 적었지만 규칙이 있어보이지 않는다.
다음을 보자:
- fix comment stripping
- fixing broken links
- Bit of refactoring
- Check whether links do exist and throw exception
- Fix sitemap include (to work on case sensitive linux)
이 메시지는 어느 곳이 변경되었는지가 없기 때문에 명확하게 어떤 변경이 있는지 알기 어렵다.
따라서 (docs, dos-parser, ocmpiler, scenario-runner, ...) 등 어느 곳이 변경되었는지 나타내는게 좋을것이다.
물론, 이런 정보로도 찾으면 찾을 수 있겠지만 느릴것이다.
그리고 git history를 보면 어느 곳을 변경한건지 나타내려고 한다. 단지 규칙이 없을 뿐
커밋 메시지 형식
<type>(<scope>): <subject>
<BLANK LINE>
<body>
<BLANK LINE>
<footer>
커밋 메시지에서 한 줄은 100자를 넘을 수 없다.
그래야 여러가지 git 도구 또는 github에서 읽기 쉽습니다.
(길면 글자가 짤리기 때문이다)
제목 줄 (subject line) : 메시지의 첫 번째 줄
제목 줄은 변경점에 대한 간단한 설명이 포함된다.
<type> 에 적어도 되는 항목
- feat (feature) : 기능
- fix (bug fix) : 버그 수정
- docs (documentation) : 문서
- style (formatting, missing semi colons, …) : 스타일 변경 (형식, 세미콜론 누락 등)
- refactor : 리팩토링
- test (when adding missing tests) : 테스트
- chore (maintain) : 빌드, 패키지 관련 (업데이트 등)
<scope> 에 적어도 되는 항목
scope는 커밋 변경 위치를 지정하는 모든 것이 될 수 있다.
예를 들면 $location, $browser, $compile, $rootScope, ngHref, ngClick, ngView, etc...
<subject> 부분
- 명령형으로, 현재 시제를 사용 : change(O) → changed(X), changes(X)
- 첫 글자를 소문자로
- 마지막에 "." 을 쓰지 말것
메시지 본문 (Message body)
- 명령형으로, 현재 시제를 사용 : change(O) → changed(X), changes(X)
- 변경 이유와 이전 코드와의 차이점을 포함한다.
http://365git.tumblr.com/post/3308646748/writing-git-commit-messages
http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html
메시지 하단 (Message footer)
주요 변경 사항 (Breaking changes)
모든 주요 변경 사항은 변경점(change), 변경 이유(justification), 마이그레이션 참고사항(migration notes) 과 함께 하단에 작성한다.
BREAKING CHANGE: isolate scope bindings definition has changed and
the inject option for the directive controller injection was removed.
To migrate the code follow the example below:
Before:
scope: {
myAttr: 'attribute',
myBind: 'bind',
myExpression: 'expression',
myEval: 'evaluate',
myAccessor: 'accessor'
}
After:
scope: {
myAttr: '@',
myBind: '@',
myExpression: '&',
// myEval - usually not useful, but in cases where the expression is assignable, you can use '='
myAccessor: '=' // in directive's template change myAccessor() to myAccessor
}
The removed `inject` wasn't generaly useful for directives so there should be no code using it.
이슈 해결 (Referencing issues)
이슈가 해결되면 하단에 다음과 같이 "Closes" 키워드를 넣어서 추가해야한다.
Closes #234
해결 이슈가 여러개 인 경우 다음과 같이 적음:
Closes #123, #245, #992
Examples
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)
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
feat(directive): ng:disabled, ng:checked, ng:multiple, ng:readonly, ng:selected
New directives for proper binding these attributes in older browsers (IE).
Added coresponding description, live examples and e2e tests.
Closes #351
style($location): add couple of missing semi colons
docs(guide): updated fixed docs from Google Docs
Couple of typos fixed:
- indentation
- batchLogbatchLog -> batchLog
- start periodic checking
- missing brace
feat($compile): simplify isolate scope bindings
Changed the isolate scope binding options to:
- @attr - attribute binding (including interpolation)
- =model - by-directional model binding
- &expr - expression execution binding
This change simplifies the terminology as well as
number of choices available to the developer. It
also supports local name aliasing from the parent.
BREAKING CHANGE: isolate scope bindings definition has changed and
the inject option for the directive controller injection was removed.
To migrate the code follow the example below:
Before:
scope: {
myAttr: 'attribute',
myBind: 'bind',
myExpression: 'expression',
myEval: 'evaluate',
myAccessor: 'accessor'
}
After:
scope: {
myAttr: '@',
myBind: '@',
myExpression: '&',
// myEval - usually not useful, but in cases where the expression is assignable, you can use '='
myAccessor: '=' // in directive's template change myAccessor() to myAccessor
}
The removed `inject` wasn't generaly useful for directives so there should be no code using it.
```a