변경 로그 항목

이 가이드는 변경 로그 항목 파일을 생성하는 시점과 방법에 대한 지침과 변경 로그 프로세스에 대한 정보와 이력을 포함합니다.

개요

우리의 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

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은 이제 모든 텍스트에 시스템 글꼴을 사용합니다.”
  • 같은 릴리스에서 도입된 회귀를 수정한 경우(즉, 월별 릴리스 후보에서 도입된 버그를 수정) 변경 로그 항목이 없어야 합니다.
  • 개발자에게 표시되는 모든 변경 사항(예: 리팩토링, 기술 부채 해소, 테스트 스위트 변경)은 변경 로그 항목이 없어야 합니다. 예: “Cycle Analytics 모델 사양에서 생성된 데이터베이스 레코드 감소.”
  • 커뮤니티 구성원으로부터의 모든 기여는 기여자가 원한다면 이러한 지침과 관계없이 변경 로그 항목이 있을 수 있습니다. 예: “검색 결과 페이지에서 오타를 수정했습니다. (Jane Smith)”

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

좋은 변경 로그 항목은 설명적이고 간결해야 합니다. 변경 사항에 대해 전혀 맥락이 없는 독자에게 설명해야 합니다. 간결성과 설명성을 모두 갖추는 데 어려움이 있다면 설명성이 더 중요합니다.

  • 나쁨: 프로젝트 순서를 이동합니다.
  • 좋음: “프로젝트 이동” 드롭다운 상단에 사용자의 즐겨찾기 프로젝트를 표시합니다.

첫 번째 예시는 변경이 이루어진 위치나 이유, 사용자가 얻는 혜택에 대한 맥락을 제공하지 않습니다.

  • 나쁨: 클립보드에 (일부 텍스트)를 복사합니다.
  • 좋음: 복사되고 있는 내용을 나타내도록 “클립보드에 복사” 툴팁을 업데이트합니다.

다시 한 번, 첫 번째 예시는 불분명하고 맥락을 제공하지 않습니다.

  • 나쁨: 미니 파이프라인 그래프 및 빌드 드롭다운에서 CSS 및 HTML 문제 수정 및 개선.
  • 좋음: 미니 파이프라인 그래프 및 빌드 드롭다운에서 툴팁 및 호버 상태 수정.

첫 번째 예시는 구현 세부정보에 너무 초점을 맞추고 있습니다. 사용자는 우리가 CSS 및 HTML을 변경했다는 사실에 신경 쓰지 않으며, 그 변화의 _최종 결과_에 관심이 있습니다.

  • 나쁨: find_commits_by_message_with_elastic에서 반환된 Commit 객체 Array의 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가 이제 업데이트되었습니다.

인터랙티브 리베이스에 대한 자세한 정보는 Git 문서를 참조하세요.

역사 및 이유

이 방법은 기본 GitLab 코드베이스에서 채택되었으며, 우리는 이 워크플로우가 매력적이고 익숙하다는 것을 발견했습니다.

개발 문서로 돌아가기