변경 로그 항목

이 가이드에는 변경 로그 항목을 생성하는 시기 및 방법에 대한 지침과 함께, 변경 로그 프로세스의 정보와 이력이 포함되어 있습니다.

개요

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

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

  • 추가됨
  • 수정됨
  • 변경됨
  • 사용 중지됨
  • 제거됨
  • 보안
  • 성능
  • 기타

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

git 벤더를 gitlab로 업데이트

이제 gitaly를 사용하여 git을 컴파일하므로 git 버전은 매니페스트에서 알 수 없습니다. 대신 gitaly 버전을 가져오고 있습니다. CVE가 나온 이전 버전과 일치하지 않도록 `gitlab`으로 벤더 필드를 업데이트합니다.

Changelog: 변경됨

변경 로그를 생성하는 동안 GitLab은 병합 요청을 커밋에 자동으로 링크합니다. 병합 요청을 재정의하려면 MR 트레일러를 사용하여 대체 병합 요청을 지정할 수 있습니다: 

git 벤더를 gitlab로 업데이트

이제 gitaly를 사용하여 git을 컴파일하므로 git 버전은 매니페스트에서 알 수 없습니다. 대신 gitaly 버전을 가져오고 있습니다. CVE가 나온 이전 버전과 일치하지 않도록 `gitlab`으로 벤더 필드를 업데이트합니다.

Changelog: 변경됨
MR: https://gitlab.com/foo/bar/-/merge_requests/123

값은 병합 요청의 전체 URL이어야 합니다.

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

  • 어떤 사용자가 직면하는 변경 사항 은 변경 로그 항목이 있어야 합니다. 예: “GitLab이 이제 모든 텍스트에 시스템 글꼴을 사용합니다.”
  • 동일한 릴리스에서 도입된 후 수정된 회귀의 수정(예: 월간 릴리스 후보 기간 동안 도입된 버그 수정) 은 변경 로그 항목이 없어야 합니다.
  • 개발자에게 영향을 주는 변경 사항(예: 리팩터링, 기술 부채 개선, 테스트 수트 변경) 은 변경 로그 항목이 없어야 합니다. 예: “사이클 분석 모델 사양에서 생성된 데이터베이스 레코드 감소.”
  • 참여자의 기여(사소한 것이라도) 은 기여자가 원하는 경우 이러한 지침과 관계없이 변경 로그 항목이 있을 수 있습니다. 예: “검색 결과 페이지의 오탈자 수정. (Jane Smith)”

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

좋은 변경 로그 항목은 설명적이고 간결해야 합니다. 변경에 대해 전혀 컨텍스트가 없는 독자에게 설명해야 합니다. 간결하고 설명적으로 하는 데 어려움이 있다면 설명적인 쪽으로 기울이세요.

  • 나쁨: 프로젝트 주문으로 이동합니다.
  • 좋음: 사용자의 주목받는 프로젝트를 “프로젝트로 가기” 드롭다운 상단에 표시합니다.

첫 번째 예시는 변화가 일어난 위치나 그것이 왜, 어떻게 사용자에게 이득이 되었는지에 대한 컨텍스트를 제공하지 않습니다.

  • 나쁨: (일부 텍스트)를 클립보드로 복사합니다.
  • 좋음: “클립보드로 복사” 툴팁을 업데이트하여 복사되는 내용을 표시합니다.

다시 말해, 첫 번째 예시는 너무 모호하여 컨텍스트를 제공하지 않습니다.

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

첫 번째 예시는 너무 구현 세부 사항에 집중되어 있습니다. 사용자는 우리가 CSS 및 HTML을 변경했다는 것이 아니라 그 변경의 _최종 결과_에 대해 관심이 있습니다.

  • 나쁨: find_commits_by_message_with_elastic에서 반환된 Commit 객체의 배열에서 nil을 제거합니다.
  • 좋음: Elasticsearch 결과가 가비지 컬렉트된 커밋을 참조하는 데 의한 500 에러를 수정합니다.

첫 번째 예시는 어떻게 우리가 무엇을 고쳤는지에 초점을 맞추고, 고친 것보다는 그것이 무엇인지에 대해 집중합니다. 다시 작성된 버전은 사용자에게 분명히 최종 혜택_을 설명하고, _언제 (Elasticsearch로 커밋 검색) 수정되었는지 명확하게 설명합니다.

가장 좋은 판단력을 발휘하고, 컴파일된 변경 로그를 읽는 사람의 입장에 서서 가치를 더하는지, 변경 사항을 _어디_와 _왜_에 대한 컨텍스트를 제공하는지 고민해보세요.

변경 로그 항목 생성 방법

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

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

git commit --amend

그런 다음 Changelog 트레일러를 커밋 메시지에 추가합니다. 이전 커밋을 이미 원격 브랜치에 푸시했으면 새 커밋을 강제로 푸시해야 합니다: 

git push -f origin your-branch-name

오래된 커밋을 수정하려면(또는 여러 커밋을 수정하려면) git rebase -i HEAD~N을 사용하며, 여기서 N은 리베이스할 마지막 N개의 커밋 수입니다. 브랜치에서 3개의 커밋 A, B, C를 가지고 있다고 가정해봅시다. 커밋 B를 업데이트하려면 다음을 실행하세요: 

git rebase -i HEAD~2

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

pick B 커밋 B의 제목
pick C 커밋 C의 제목

커밋 B를 업데이트하려면 pick을 reword로 변경한 후 텍스트 편집기에서 저장 및 종료합니다. 종료 후 Git은 새 텍스트 편집기 인스턴스를 사용자에게 표시하여 커밋 B의 커밋 메시지를 편집할 수 있게 합니다. 트레일러를 추가한 후 텍스트 편집기에서 저장하고 종료하세요. 모든 게 잘 되었다면 커밋 B가 업데이트된 것입니다.

자세한 내용은 인터랙티브 리베이스에 대한 Git 문서를 확인하세요. (https://git-scm.com/book/en/v2/Git-Tools-Rewriting-History)

이력과 근거

이 방법은 주요 GitLab 코드베이스에서 채택되었으며, 간편함과 익숙함을 강조했다는 이유로 선택되었습니다.

개발 문서로 돌아가기