변경 로그 항목

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

개요

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

Changelog 트레일러는 다음과 같은 값을 허용합니다.

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

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

Git 벤더를 gitlab로 업데이트

이제 gitaly를 사용하여 git을 컴파일하는데, git 버전은 더 이상 매니페스트에서 알 수 없으며, 대신 gitaly 버전을 가져옵니다. CVE가 이전 버전과 일치하지 않도록 우리의 벤더 필드를 `gitlab`으로 업데이트합니다.

Changelog: changed

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

연결된 병합 요청 재정의

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

Git 벤더 업데이트를 gitlab로 변경

이제 gitaly를 사용하여 git을 컴파일하는데, git 버전은 더 이상 매니페스트에서 알 수 없으며, 대신 gitaly 버전을 가져옵니다. CVE가 이전 버전과 일치하지 않도록 우리의 벤더 필드를 `gitlab`으로 업데이트합니다.

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

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

GitLab Enterprise 변경 사항

변경 사항이 GitLab Enterprise Edition 전용인 경우, 반드시 트레일러 EE: true를 추가해야 합니다.

Git 벤더를 gitlab로 업데이트

이제 gitaly를 사용하여 git을 컴파일하는데, git 버전은 더 이상 매니페스트에서 알 수 없으며, 대신 gitaly 버전을 가져옵니다. CVE가 이전 버전과 일치하지 않도록 우리의 벤더 필드를 `gitlab`으로 업데이트합니다.

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에서 반환된 커밋 객체 배열의 nil을 제거합니다.
좋음: Elasticsearch 결과가 가비지 수집된 커밋을 참조하여 발생한 500 오류 수정

첫 번째 예시는 어떻게 우리가 무엇을 고쳤는지에 초점을 맞추고 있으며 실제로 어떤 문제를 고친지에 관한 설명을 제공하지 않습니다. 재작된 버전은 사용자에게 어떤 문제를 해결하는지 명확히 설명하고 있으며 (500 오류 감소), 언제 (Elasticsearch를 사용하여 커밋을 검색할 때) 설명하고 있습니다.

여러분 자신의 판단을 사용하고 종합해보세요, 그리고 컴파일 된 변경 로그를 읽는 사람의 입장에서 자신을 두세요. 이 항목이 가치가 있는가요? 변경 사항이 _어디_와 _왜_생성되었는지 충분한 컨텍스트를 제공합니까?

변경 로그 항목 생성 방법

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

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

git commit --amend

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

git push -f origin 브랜치이름

이전 커밋(또는 여러 개의 커밋)을 편집하려면 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를 업데이트하려면 pick를 reword로 변경한 후 편집기를 저장하고 닫습니다. 저장 및 종료 후 Git이 커밋 B의 커밋 메시지를 편집할 수 있는 새 편집기 인스턴스를 표시합니다. 여기에 트레일러를 추가한 후 편집기를 저장하고 닫으면 커밋 B가 업데이트됩니다.

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

개발 문서로 돌아가기