Wagtail Documentation
코드 커밋하기¶
이 섹션은 Wagtail 핵심 팀이나 Wagtail에 코드를 커밋하는 과정에 관심 있는 모든 분들을 위한 것입니다.
코드는 다른 리뷰어나 커미터에게 최소 한 번 리뷰를 받은 후에만 커밋해야 합니다. 단, 사소한 문서 변경이나 오타 수정은 예외입니다. 리뷰 후에 추가적인 코드 변경이 이루어진 경우, 논란의 여지가 없고 새로운 버그를 유발할 가능성이 거의 없는 작은 변경이라면 추가 리뷰 없이 커밋할 수 있습니다.
대부분의 코드 기여는 GitHub의 풀 리퀘스트(pull request) 형태로 이루어집니다. 풀 리퀘스트는 GitHub에서 직접 병합(merge)해서는 안 됩니다. 단, ‘Squash and merge’ 옵션을 사용하여 병합할 수 있는 작은 문서 수정은 예외입니다. 대신, 커미터가 코드를 로컬로 체크아웃하고, 변경 사항을 검토하고 리베이스(rebase)하며, CHANGELOG.txt 와 릴리스 노트를 업데이트한 후, 마지막으로 코드를 main 브랜치에 푸시(push)해야 합니다. 이 과정에 대해서는 아래에서 더 자세히 설명합니다.
로컬에서 코드 체크아웃하기¶
코드가 풀 리퀘스트로 제출된 경우, 변경 사항을 가져와서(fetch) Wagtail 저장소에서 체크아웃해야 합니다. 이 작업을 간단하게 하려면 다음\ git\ 별칭(alias)을\ ~/.gitconfig\ 파일에 추가하면 됩니다 (이때\ upstream\ 이\ wagtail/wagtail\ 이라고 가정합니다):
[alias]
pr = !sh -c "git fetch upstream pull/${1}/head:pr/${1} && git checkout pr/${1}"
이제\ git pr xxxx\ 를 실행하여 풀 리퀘스트 번호\ xxxx\ 를 체크아웃할 수 있습니다.
main 브랜치에 리베이스하기¶
이제 코드를 받았으니, 커밋들을 main 브랜치에 리베이스해야 합니다. 작은 변경 사항의 경우 병합 커밋(merge commit)이 커밋 히스토리를 읽기 어렵게 만들기 때문에, 병합보다는 리베이스가 선호됩니다.
리베이스 과정에서 오타나 서식 같은 작은 실수를 수정할 수 있습니다.\ git rebase --interactive\ 는 이 작업에 아주 훌륭한 도구입니다.
이상적으로는, 이 기회를 활용하여 변경 사항을 몇 개의 커밋으로 스쿼시(squash)하여 각 커밋이 의미 있는 단일 변경 사항을 만들도록 (그리고 아무것도 깨뜨리지 않도록) 해야 합니다. 변경 사항의 특성상 이것이 불가능한 경우, 커밋 히스토리에서 어떤 것이 더 읽기 쉬울지에 따라 하나의 커밋으로 스쿼시하거나 모든 커밋을 스쿼시하지 않은 상태로 두는 것이 허용됩니다.
# Wagtail에서 최신 커밋 가져오기
git fetch upstream
git checkout main
git merge --ff-only upstream/main
# 이 풀 리퀘스트를 main에 리베이스하기
git checkout pr/xxxx
git rebase main
# main을 이 커밋으로 업데이트하기
git checkout main
git merge --ff-only pr/xxxx
CHANGELOG.txt 와 릴리스 노트 업데이트하기¶
참고
이 작업은 변경 사항이 검토되고 승인된 후에 핵심 커미터에 의해서만 수행되어야 합니다.
Wagtail에 대한 모든 중요한 변경 사항은\ CHANGELOG.txt\ 와 현재 버전의 릴리스 노트에 항목이 추가되어야 합니다.
CHANGELOG.txt\ 에는 각 릴리스의 새로운 기능, 리팩토링, 버그 수정에 대한 간략한 요약이 포함됩니다. 각 요약은 한 줄이어야 합니다. 사용자에게 가장 관련성 높은 변경 사항을 쉽게 식별할 수 있도록 항목은 다음 순서로 그룹화됩니다:
주요 기능 (접두사 없음) - 사용자가 새 릴리스로 업그레이드하도록 유도할 만한 기능들
사소한 개선 사항 (접두사 없음) - 개발자 또는 최종 사용자 경험에 대한 기타 개선 사항
버그 수정 (“Fix:” 접두사 사용) - 이전 릴리스의 잘못된 동작을 해결하는 사항
문서 (“Docs:” 접두사 사용) - 특정 코드 변경과 관련 없는 문서 변경 사항; 재구성, 튜토리얼, 레시피 등
유지보수 (“Maintenance:” 접두사 사용) - 개발자나 최종 사용자에게 눈에 띄는 영향을 주지 않는 코드나 도구의 정리, 리팩토링 및 기타 변경 사항
기여자의 이름은 요약 끝에 괄호 안에 추가해야 합니다. 예를 들면 다음과 같습니다:
* Fix: 다중 이미지 업로더에서 추가된 태그가 이제 올바르게 저장됩니다 (Alex Smith)
각 버전의 릴리스 노트에는 각 주요 기능에 대한 더 자세한 설명이 별도의 제목 아래에 포함됩니다. 사소한 개선 사항(“Other features”), 버그 수정, 문서 및 유지보수는 적절한 제목 아래에 글머리 기호로 나열됩니다. 이는 변경 로그에서 복사하여 접두사(“Fix:”, “Docs:” 또는 “Maintenance:”)를 제거하여 사용할 수 있습니다. 하위 호환성 관련 참고 사항도 포함되어야 합니다. 이전 릴리스 노트를 예시로 참고하세요. 각 버전의 릴리스 노트는\ docs/releases/x.x.x.md\ 에서 찾을 수 있습니다.
기여자가 새로운 사람이고 이것이 Wagtail에 대한 첫 기여라면, 그들은\ CONTRIBUTORS.md\ 목록에 추가되어야 합니다. 기여자는 시간순으로 추가되며, 새로운 기여자는 목록의 맨 아래에 추가됩니다. 선호하는 이름을 사용하세요. 일반적으로 기여자의 이름은 GitHub 프로필에서 찾을 수 있습니다. 확실하지 않거나 프로필에 이름이 없다면, 어떻게 이름을 기재하고 싶은지 물어보세요.
병합할 변경 사항이 단일 커밋으로 만들기에 충분히 작다면, CHANGELOG.txt\ , 릴리스 노트, 기여자 목록에 대한 추가 사항으로 이 단일 커밋을 수정(amend)하세요:
git add CHANGELOG.txt docs/releases/x.x.x.md CONTRIBUTORS.md
git commit --amend --no-edit
변경 사항이 단일 커밋에 맞지 않는 경우,\ CHANGELOG.txt\ , 릴리스 노트, 기여자 목록에 대한 업데이트를 포함하는 새 커밋을 만드세요. 커밋 메시지는\ Release notes for #xxxx\ 여야 합니다:
git add CHANGELOG.txt docs/releases/x.x.x.md CONTRIBUTORS.md
git commit -m 'Release notes for #xxxx'
main 브랜치에 푸시하기¶
이제 변경 사항을 main 브랜치에 푸시할 준비가 되었습니다.
# 모든 것이 괜찮은지 확인
git log upstream/main..main --oneline
git push --dry-run upstream main
# 커밋 푸시하기!
git push upstream main
git branch -d pr/xxxx
실수를 했을 때¶
괜찮습니다! 누구나 실수를 합니다. 최근에 병합된 변경 사항이 부정적인 영향을 미친다는 것을 알게 되면, 해당 변경 사항을 되돌리는 새 풀 리퀘스트를 생성하고 리뷰를 기다리지 않고 병합하세요. 이 풀 리퀘스트는 변경 사항에 대한 추가 문서 역할을 하며 CI 테스트를 거치게 됩니다.
다른 사람의 풀 리퀘스트에 커밋 추가하기¶
wagtail/wagtail에 대한 쓰기 접근 권한이 있는 GitHub 사용자(핵심 멤버)는 기여자의 풀 리퀘스트 브랜치에 커밋을 추가할 수 있습니다.
기여자의 사용자 이름이 johndoe이고 그의 풀 리퀘스트 브랜치 이름이 foo라고 가정합니다:
git clone git@github.com:wagtail/wagtail.git
cd wagtail
git remote add johndoe git@github.com:johndoe/wagtail.git
git fetch johndoe foo
git checkout johndoe/foo
# 변경 작업 수행
# 변경 사항 커밋
git push johndoe HEAD:foo