변경 로그 항목

이 안내서에는 변경 로그 항목 파일을 생성하는 방법과 시기에 대한 지침, 그리고 변경 로그 프로세스에 대한 정보와 이력이 포함되어 있습니다.

개요

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

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

  • added
  • fixed
  • changed
  • deprecated
  • removed
  • security
  • performance
  • other

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

git 벤더를 gitlab으로 업데이트

이제 gitaly를 사용하여 git을 컴파일하기 때문에 git 버전은 manifest에서 알 수 없습니다. 대신 gitaly 버전을 얻습니다. 오래된 버전과 일치하는 cve를 피하기 위해 벤더 필드를 `gitlab`으로 업데이트합니다.

Changelog: changed

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

git 벤더를 gitlab으로 업데이트

이제 gitaly를 사용하여 git을 컴파일하기 때문에 git 버전은 manifest에서 알 수 없습니다. 대신 gitaly 버전을 얻습니다. 오래된 버전과 일치하는 cve를 피하기 위해 벤더 필드를 `gitlab`으로 업데이트합니다.

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 객체의 배열에서 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 번호의 커밋입니다. 예를 들어 브랜치에 A, B 및 C 등 3개의 커밋이있는 경우, 커밋 B를 업데이트하려면 다음을 실행해야 합니다:

git rebase -i HEAD~2

이는 마지막 두 개의 커밋에 대한 대화형 리베이스 세션을 시작합니다. 시작하면 Git은 다음과 같은 내용을 가진 텍스트 편집기를 엽니다:

pick B Commit B의 제목
pick C Commit C의 제목

커밋 B를 업데이트하려면 pickreword로 변경한 다음 편집기에서 저장하고 종료합니다. 닫힌 후, Git은 커밋 B의 새 텍스트 편집기 인스턴스를 표시하여 커밋 메시지를 편집할 수 있게 합니다. 트레일러를 추가한 다음 저장하고 편집기를 종료합니다. 모든 것이 원활하게 진행되었다면 커밋 B가 업데이트됩니다.

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

역사 및 이유

이 방법은 우리가 매력적이고 익숙한 워크플로우를 발견하여, 주력 GitLab 코드베이스에서 채택되었습니다.


개발 문서로 돌아가기