변경 로그 항목

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

개요

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

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

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

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

Git 벤더를 gitlab으로 업데이트

이제 git을 컴파일하기 위해 gitaly를 사용하고 있기 때문에 manifest에서 git 버전을 알 수 없습니다. 대신 gitaly 버전을 가져오고 있습니다. 이전 버전과 일치하는 cve를 피하기 위해 우리의 vendor 필드를 `gitlab`으로 업데이트합니다.

Changelog: changed

만약 병합 요청에 여러 개의 커밋이 있다면, 첫번째 커밋에 Changelog 항목을 추가해야 합니다. 이렇게 하면 커밋이 스쿼시될 때 올바른 항목이 생성되도록 보장됩니다.

연결된 병합 요청 재지정

변경 로그를 생성할 때 GitLab은 병합 요청을 커밋에 연결합니다. 연결할 다른 병합 요청을 지정하려면 MR 트레일러를 사용할 수 있습니다:

Git 벤더를 gitlab으로 업데이트

이제 git을 컴파일하기 위해 gitaly를 사용하고 있기 때문에 manifest에서 git 버전을 알 수 없습니다. 대신 gitaly 버전을 가져오고 있습니다. 이전 버전과 일치하는 cve를 피하기 위해 우리의 vendor 필드를 `gitlab`으로 업데이트합니다.

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

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

GitLab 엔터프라이즈 변경 사항

변경 사항이 GitLab 엔터프라이즈 에디션에만 적용되는 경우 반드시 EE: true 트레일러를 추가해야 합니다:

Git 벤더를 gitlab으로 업데이트

이제 git을 컴파일하기 위해 gitaly를 사용하고 있기 때문에 manifest에서 git 버전을 알 수 없습니다. 대신 gitaly 버전을 가져오고 있습니다. 이전 버전과 일치하는 cve를 피하기 위해 우리의 vendor 필드를 `gitlab`으로 업데이트합니다.

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

CE 및 EE에 모두 적용되는 변경 사항에 해당하는 트레일러는 추가하지 마십시오.

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

일반, 포스트, 또는 데이터 마이그레이션이 도입되는 모든 변경은 기능 플래그가 비활성화되어 있더라도 변경 로그 항목을 꼭 가지고 있어야 합니다.
보안 수정은 Changelog 트레일러가 security로 설정된 변경 로그 항목을 반드시 가져야 합니다.
사용자가 볼 수 있는 어떠한 변경 사항도 꼭 변경 로그 항목을 가져야 합니다. 예: “GitLab이 이제 모든 텍스트에 시스템 글꼴을 사용합니다.”
REST 및 GraphQL API에 대한 클라이언트 측 변경 사항도 꼭 변경 로그 항목을 가져야 합니다.
고급 검색 마이그레이션가 도입되는 경우 꼭 변경 로그 항목을 가져야 합니다.
동일한 릴리스에서 도입되었다가 수정된 리그레이션에 대한 수정(예: 월간 릴리스 후보 동안 도입된 버그 수정)은 변경 로그 항목을 가지지 말아야 합니다.
개발자를 대상으로 한 모든 변경 사항(예: 리팩터링, 기술 부채 개선, 또는 테스트 스위트 변경)은 변경 로그 항목을 가지지 말아야 합니다. 예: “사이클 분석 모델 스펙 중에 생성된 데이터베이스 레코드를 줄입니다.”
아주 작은 경우라도 커뮤니티 회원의 모든 기여는 기여자가 원하는 경우 이러한 지침과 무관하게 변경 로그 항목을 가질 수 있습니다.
실험 변경 사항은 반드시 변경 로그 항목을 가지지 말아야 합니다.
문서 변경만 포함된 MR은 변경 로그 항목을 가지지 말아야 합니다.

다른 정보를 보려면 기능 플래그로 변경 로그 항목 다루기를 참조하세요.

좋은 변경 로그 항목 작성

좋은 변경 로그 항목은 구체적이고 간결해야 합니다. 변경에 대한 아무런 맥락이 없는 독자에게도 변경을 설명해야 합니다. 간결하고 구체적인 데 애를쓰는 데 어려움을 겪는다면 구체적인 쪽으로 적는 것이 좋습니다.

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

첫번째 예제는 변경이 어디에서 이루어졌는지, 또는 왜, 또 어떻게 사용자에게 이점을 제공하는지 알려주지 않습니다.

나쁨: (일부 텍스트)를 클립보드에 복사합니다.
좋음: “클립보드에 복사” 도구 팁을 업데이트하여 무엇이 복사되고 있는지를 나타냅니다.

다시, 첫번째 예는 너무 모호하며 맥락이 없습니다.

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

첫번째 예제는 구체적인 구현 세부 정보에 너무 초점을 맞추고 있습니다. 사용자는 우리가 CSS와 HTML을 변경했다는 사실에는 관심이 없습니다. 그들이 관심을 가지는 것은 이러한 변경의 _최종 결과_입니다.

나쁨: find_commits_by_message_with_elastic에서 반환된 새로운 커밋 객체 배열의 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 세 개의 커밋이 있다면, 커밋 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 설명서를 참조하세요.

개발 문서로 돌아가기