변경 로그 항목

요약

CHANGELOG.md 파일의 각 목록 항목, 즉 **항목(entry)**은 Git 커밋의 제목 줄에서 생성됩니다. Git 트레일러는 변경 사항을 커밋할 때 추가합니다. 변경 로그에 포함할 Git 커밋 예시는 다음과 같습니다:

CHANGELOG.md 파일의 각 목록 항목, 즉 **항목(entry)**은 Git 커밋의 제목 줄에서 생성됩니다. 커밋에 Changelog Git 트레일러가 포함되어 있을 때 해당 커밋이 포함됩니다. 변경 로그를 생성할 때 작성자 및 머지 리퀘스트 세부 정보는 자동으로 추가됩니다.

변경 로그 항목 생성 방법#

Git 트레일러는 변경 사항을 커밋할 때 추가합니다. 이는 원하는 텍스트 에디터를 사용하여 수행할 수 있습니다. 변경 로그를 추가하려면:

사용 사례에 맞는 트레일러를 선택하세요.

변경 로그에 포함할 Git 커밋 예시는 다음과 같습니다:

Update git vendor to GitLab

Now that we are using Gitaly to compile Git, the Git version isn't known
from the manifest. Instead, we are getting the Gitaly version. Update our
vendor field to be `gitlab` to avoid CVE matching old versions.

Changelog: changed

변경 사항을 푸시하세요.

머지 리퀘스트에 여러 커밋이 있는 경우, 반드시 Changelog 항목을 첫 번째 커밋에 추가하세요. 이렇게 하면 커밋이 스쿼시될 때 올바른 항목이 생성됩니다.

기존 커밋에 트레일러를 추가하려면 커밋을 수정(amend)하거나(가장 최근 커밋인 경우), git rebase -i를 사용하여 대화형 리베이스를 수행해야 합니다.

마지막 커밋을 업데이트하려면 다음을 실행하세요:

git commit --amend

그런 다음 커밋 메시지에 Changelog 트레일러를 추가할 수 있습니다. 이미 원격 브랜치에 이전 커밋을 푸시한 경우, 새 커밋을 강제 푸시해야 합니다:

git push -f origin your-branch-name

이전 커밋(또는 여러 커밋)을 편집하려면 git rebase -i HEAD~N을 사용하세요. 여기서 N은 리베이스할 마지막 N개의 커밋 수입니다. 예를 들어, 브랜치에 커밋이 세 개 있고 두 번째 커밋만 업데이트하려면 다음을 실행해야 합니다:

git rebase -i HEAD~2

이 명령은 마지막 두 커밋에 대한 대화형 리베이스 세션을 시작합니다. 시작되면 Git은 다음과 같은 내용의 텍스트 에디터를 표시합니다:

pick B Subject of commit B
pick C Subject of commit C

커밋 B를 업데이트하려면 pick을 reword로 변경한 후 에디터를 저장하고 종료하세요. 종료되면 Git은 커밋 B의 커밋 메시지를 편집할 수 있는 새 텍스트 에디터 인스턴스를 표시합니다. 트레일러를 추가한 후 에디터를 저장하고 종료하세요. 모든 작업이 올바르게 진행되었다면 커밋 B가 업데이트됩니다.

원격 브랜치에 이미 존재하는 커밋을 변경했으므로, 원격 브랜치에 푸시할 때 --force-with-lease 플래그를 사용해야 합니다:

git push origin your-branch-name --force-with-lease

대화형 리베이스에 대한 자세한 내용은 Git 문서를 참조하세요.

연결된 머지 리퀘스트 재정의#

GitLab은 변경 로그를 생성할 때 머지 리퀘스트를 커밋에 자동으로 연결합니다. 연결할 머지 리퀘스트를 재정의하려면 MR 트레일러를 사용하여 대체 머지 리퀘스트를 지정할 수 있습니다:

Update git vendor to gitlab

Now that we are using gitaly to compile git, the git version isn't known
from the manifest, instead we are getting the gitaly version. Update our
vendor field to be `gitlab` to avoid cve matching old versions.

Changelog: changed
MR: https://gitlab.com/foo/bar/-/merge_requests/123

값은 머지 리퀘스트의 전체 URL이어야 합니다.

GitLab Enterprise 변경 사항#

변경 사항이 GitLab Enterprise Edition에만 해당하는 경우, 반드시 EE: true 트레일러를 추가해야 합니다:

Update git vendor to gitlab

Now that we are using gitaly to compile git, the git version isn't known
from the manifest, instead we are getting the gitaly version. Update our
vendor field to be `gitlab` to avoid cve matching old versions.

Changelog: changed
MR: https://gitlab.com/foo/bar/-/merge_requests/123
EE: true

EE와 CE 모두에 적용되는 변경 사항에는 이 트레일러를 추가하지 마세요.

변경 로그 항목이 필요한 경우#

일반, 사후(post), 또는 데이터 마이그레이션 여부와 관계없이 데이터베이스 마이그레이션을 도입하는 모든 변경 사항은 비활성화된 기능 플래그 뒤에 있더라도 반드시 변경 로그 항목이 있어야 합니다.
보안 수정은 Changelog 트레일러를 security로 설정하여 반드시 변경 로그 항목이 있어야 합니다.
사용자에게 영향을 미치는 모든 변경 사항은 반드시 변경 로그 항목이 있어야 합니다. 예: "GitLab이 이제 모든 텍스트에 시스템 폰트를 사용합니다."
REST 및 GraphQL API에 대한 클라이언트 측 변경 사항은 반드시 변경 로그 항목이 있어야 합니다. GraphQL 브레이킹 체인지를 구성하는 전체 목록을 참조하세요.
고급 검색 마이그레이션을 도입하는 모든 변경 사항은 반드시 변경 로그 항목이 있어야 합니다.
동일한 릴리즈 내에서 도입되었다가 수정된 회귀(예: 월간 릴리즈 후보 기간에 도입된 버그 수정)는 변경 로그 항목이 있어서는 안 됩니다.
개발자 대상 변경 사항(예: 리팩토링, 기술 부채 해소, 테스트 스위트 변경)은 변경 로그 항목이 있어서는 안 됩니다. 예: "Cycle Analytics 모델 스펙 실행 시 생성되는 데이터베이스 레코드 감소."
커뮤니티 구성원의 기여는 크기와 관계없이 기여자가 원하면 이 가이드라인에 관계없이 변경 로그 항목을 포함할 수 있습니다.
실험 변경 사항은 변경 로그 항목이 있어서는 안 됩니다.
문서 변경 사항만 포함된 MR은 변경 로그 항목이 있어서는 안 됩니다.

자세한 내용은 기능 플래그와 함께 변경 로그 항목을 처리하는 방법을 참조하세요.

좋은 변경 로그 항목 작성법#

좋은 변경 로그 항목은 설명적이고 간결해야 합니다. 변경 사항에 대해 전혀 모르는 독자도 이해할 수 있도록 설명해야 합니다. 간결하면서도 설명적으로 만들기 어렵다면 설명적인 쪽을 선택하세요.

나쁜 예: 프로젝트 순서로 이동.
좋은 예: "프로젝트로 이동" 드롭다운 목록의 상단에 사용자가 즐겨찾기한 프로젝트를 표시.

첫 번째 예시는 변경이 어디서 이루어졌는지, 왜 이루어졌는지, 사용자에게 어떤 이점이 있는지에 대한 맥락을 제공하지 않습니다.

나쁜 예: (일부 텍스트를) 클립보드에 복사.
좋은 예: "클립보드에 복사" 툴팁을 업데이트하여 무엇이 복사되는지 표시.

첫 번째 예시는 너무 모호하고 맥락을 제공하지 않습니다.

나쁜 예: 미니 파이프라인 그래프와 빌드 드롭다운 목록의 CSS 및 HTML 문제를 수정하고 개선.
좋은 예: 미니 파이프라인 그래프와 빌드 드롭다운 목록의 툴팁 및 호버 상태를 수정.

첫 번째 예시는 구현 세부 사항에 너무 집중합니다. 사용자는 CSS와 HTML을 변경했다는 것이 아니라 해당 변경 사항의 최종 결과를 중요시합니다.

나쁜 예: find_commits_by_message_with_elastic에서 반환된 커밋 객체 배열에서 nil을 제거.
좋은 예: Elasticsearch 결과가 가비지 컬렉션된 커밋을 참조하여 발생하는 500 오류를 수정.

첫 번째 예시는 무언가를 어떻게 수정했는지에 집중하고, 무엇을 수정했는지에는 집중하지 않습니다. 재작성된 버전은 사용자에게 제공되는 최종 이점(더 적은 500 오류)과 시기(Elasticsearch로 커밋 검색 시)를 명확하게 설명합니다.

최선의 판단을 내리고 컴파일된 변경 로그를 읽는 사람의 입장에서 생각해 보세요. 이 항목이 가치를 추가하나요? 변경이 이루어진 위치와 이유에 대한 맥락을 제공하나요?

개발 문서로 돌아가기