변경 로그 항목

이 가이드는 변경 로그 항목 파일을 생성하는 시기와 방법에 대한 지침과 우리 변경 로그 프로세스에 대한 정보 및 역사입니다.

개요

우리의 CHANGELOG.md 파일의 각 목록 항목 또는 항목은 Git 커밋의 주제 행에서 생성됩니다. 커밋은 Changelog Git 트레일러를 포함할 때 포함됩니다. 변경 로그를 생성할 때는 작성자 및 병합 요청 세부정보가 자동으로 추가됩니다.

Changelog 트레일러는 다음 값을 허용합니다:

  • added: 새로운 기능
  • fixed: 버그 수정
  • changed: 기능 변경
  • deprecated: 새로운 사용 중지
  • removed: 기능 제거
  • security: 보안 수정
  • performance: 성능 개선
  • other: 기타

변경 로그에 포함할 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 항목을 추가해야 합니다.

이렇게 하면 커밋이 병합될 때 올바른 항목이 생성됩니다.

관련 병합 요청 재정의

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 엔터프라이즈 변경 사항

변경 사항이 오직 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 모두에 적용되는 변경 사항에는 트레일러를 추가하지 마십시오.

어떤 경우에 변경 로그 항목이 필요합니까?

  • 데이터베이스 마이그레이션을 도입하는 모든 변경 사항은 정기적으로든, 사후적으로든, 데이터 마이그레이션이든 반드시 변경 로그 항목이 있어야 하며, 비활성화된 기능 플래그 뒤에 있더라도 마찬가지입니다.
  • 보안 수정은 반드시 변경 로그 항목이 있어야 하며, Changelog 트레일러는 security로 설정되어야 합니다.
  • 사용자에게 표시되는 모든 변경 사항은 반드시 변경 로그 항목이 있어야 합니다. 예: “GitLab은 이제 모든 텍스트에 시스템 글꼴을 사용합니다.”
  • REST 및 GraphQL API에 대한 모든 클라이언트 표시 변경은 반드시 변경 로그 항목이 있어야 합니다. GraphQL 중단 변경이 무엇을 구성하는지에 대한 전체 목록을 참조하세요.
  • 고급 검색 마이그레이션을 도입하는 모든 변경 사항은 반드시 변경 로그 항목이 있어야 합니다.
  • 동일 릴리스에서 도입된 문제를 수정한 후 수정한 경우(예: 월간 릴리스 후보에서 도입된 버그 수정) 변경 로그 항목이 없도록 해야 합니다.
  • 모든 개발자 친화적인 변경(예: 리팩토링, 기술 부채 해소, 테스트 스위트 변경)은 변경 로그 항목이 없도록 해야 합니다. 예: “Cycle Analytics 모델 사양에서 생성된 데이터베이스 레코드 수 줄이기.”
  • 커뮤니티 구성원으로부터의 모든 기여는 그 양이 작더라도 기여자가 원하면 변경 로그 항목을 가질 수 있습니다.
  • 모든 실험 변경 사항은 변경 로그 항목이 없도록 해야 합니다.
  • 문서 변경만 포함된 MR은 변경 로그 항목이 없도록 해야 합니다.

자세한 내용은

기능 플래그가 있는 변경 로그 항목 처리 방법을 참조하세요.

좋은 변경 로그 항목 작성하기

좋은 변경 로그 항목은 설명적이고 간결해야 합니다. 변경 사항에 대한 전혀 맥락이 없는 독자에게 변경 사항을 설명해야 합니다. 간결하고 설명적인 부분에서 어려움이 있다면 설명적인 쪽으로 기울여야 합니다.

  • 나쁨: 프로젝트 주문으로 이동.
  • 잘함: “프로젝트로 이동” 드롭다운 목록의 상단에 사용자의 즐겨찾기 프로젝트 표시.

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

  • 나쁨: 클립보드에 (일부 텍스트)을 복사합니다.
  • 잘함: 복사되는 내용이 무엇인지 나타내도록 “클립보드에 복사” 툴팁을 업데이트합니다.

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

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

첫 번째 예시는 구현 세부 사항에 너무 집중하고 있습니다. 사용자들은 우리가 CSS와 HTML을 변경한 것에 관심이 있는 것이 아니라, 이러한 변경의 _최종 결과_에 관심이 있습니다.

  • 나쁨: find_commits_by_message_with_elastic에서 반환된 Commit 객체 배열의 nil을 제거합니다.
  • 잘함: 가비지 수집된 커밋을 참조하는 Elasticsearch 결과로 인해 발생한 500 오류 수정

첫 번째 예시는 무엇_을 수정했는지에 대한 것이 아니라 _어떻게 수정했는지에 집중하고 있습니다. 다시 작성된 버전은 사용자에게 필요한 최종 이점 (500 오류 감소)과 언제 (Elasticsearch로 커밋 검색할 때)를 명확하게 설명합니다.

최선을 다해 자신의 관점을 바꿔서 컴파일된 변경 로그를 읽는 사람의 입장에서 생각해 보세요. 이 항목이 가치를 더할까요? 어디서 그리고 왜 변경 사항이 이루어졌는지에 대한 맥락을 제공하나요?

변경 로그 항목 생성 방법

Git 트레일러는 변경 사항을 커밋할 때 추가됩니다. 이는 원하는 텍스트 편집기를 사용하여 수행할 수 있습니다. 기존 커밋에 트레일러를 추가하려면 가장 최근의 커밋을 수정하거나 git rebase -i를 사용한 인터랙티브 리베이스가 필요합니다.

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

git commit --amend

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

git push -f origin your-branch-name

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

git rebase -i HEAD~2

이 명령은 마지막 두 커밋에 대한 인터랙티브 리베이스 세션을 시작합니다. 시작되면 Git은 다음과 유사한 내용을 포함한 텍스트 편집기를 표시합니다:

pick B 커밋 B의 주제
pick C 커밋 C의 주제

B 커밋을 업데이트하려면 pick이라는 단어를 reword로 변경한 다음 편집기를 저장하고 종료하세요. 편집기를 닫으면 Git은 B 커밋의 커밋 메시지를 편집할 새로운 텍스트 편집기 인스턴스를 제공합니다. 트레일러를 추가한 후 편집기를 저장하고 종료하세요. 모든 것이 잘되었으면 B 커밋이 업데이트됩니다.

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

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

인터랙티브 리베이스에 대한 자세한 내용은 Git 문서를 참조하세요.

개발 문서로 돌아가기