변경 로그 항목

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

개요

우리의 CHANGELOG.md 파일의 각 디렉터리 또는 항목은 Git 커밋의 제목 줄에서 생성됩니다. 커밋을 포함할 때 Changelog Git trailer가 포함됩니다. 변경 로그를 생성할 때 작성자와 Merge Request 세부 정보가 자동으로 추가됩니다.

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

added
fixed
changed
deprecated
removed
security
performance
other

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

Update git vendor to gitlab

이제 우리는 git을 컴파일하기 위해 gitaly를 사용하고 있기 때문에 git 버전은 manifest에서 알려지지 않습니다. 대신에 gitaly 버전을 가져오고 있습니다. CVE와 관련이 있는 이전 버전 일치를 피하기 위해 우리의 벤더 필드를 `gitlab`으로 업데이트합니다.

Changelog: changed

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

Update git vendor to gitlab

이제 우리는 git을 컴파일하기 위해 gitaly를 사용하고 있기 때문에 git 버전은 manifest에서 알려지지 않습니다. 대신에 gitaly 버전을 가져오고 있습니다. CVE와 관련이 있는 이전 버전 일치를 피하기 위해 우리의 벤더 필드를 `gitlab`으로 업데이트합니다.

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

값은 Merge Request의 전체 URL이어야 합니다.

어떤 변경 로그 항목이 필요한가요?

모든 사용자가 직면하는 변경 사항에는 변경 로그 항목이 있어야 합니다. 예: “GitLab은 이제 모든 텍스트에 시스템 글꼴을 사용합니다.”
동일한 릴리스에서 도입되었다가 수정된(즉, 월간 릴리스 후보기간 동안 버그를 수정하는 경우) 회귀의 수정에는 변경 로그 항목이 있으면 안 됩니다.
개발자가 직면하는 모든 변경 사항(예: 리팩터링, 기술적 부채 해소, 테스트 스위트 변경)에는 변경 로그 항목이 없어야 합니다. 예: “Cycle Analytics 모델 사양에서 생성된 데이터베이스 레코드를 줄입니다.”
기여자가 원한다면 어떤 작은 기여라도 이 지침과 관계없이 변경 로그 항목이 있을 수 있습니다. 예: “검색 결과 페이지의 오타를 수정했습니다. (Jane Smith)”

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

좋은 변경 로그 항목은 구체적이고 간결해야 합니다. 변경에 대해 전혀 맥락이 없는 독자에게 해당 변경 사항을 설명해야 합니다. 간결하고 구체적으로 작성하기 어려운 경우 구체적으로 작성하는 쪽으로 하세요.

나쁨: 프로젝트 주문으로 이동하십시오.
좋음: 사용자의 주요 프로젝트를 “프로젝트로 이동” 드롭다운 상단에 표시합니다.

첫 번째 예제는 변경이 발생한 위치나 그 이유 또는 사용자에게 어떠한 혜택이 있는지의 맥락을 제공하지 않습니다.

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

다시 말해, 첫 번째 예제는 너무 모호하며 맥락을 제공하지 않습니다.

나쁨: 미니 파이프라인 그래프 및 빌드 드롭다운의 CSS 및 HTML 문제를 수정하고 향상시킵니다.
좋음: 미니 파이프라인 그래프 및 빌드 드롭다운의 툴팁 및 호버 상태를 수정합니다.

첫 번째 예제는 너무 구현 세부 사항에 초점을 맞추고 있습니다. 사용자는 우리가 CSS와 HTML을 변경했다는 대신, 그 변경의 결과에 신경을 씁니다.

나쁨: find_commits_by_message_with_elastic에서 반환된 커밋 객체의 배열에서 nil을 제거합니다.
좋음: Elasticsearch 결과가 가비지 컬렉션된 커밋을 참조하여 발생하는 500 오류를 수정합니다.

첫 번째 예제는 우리가 무엇을 어떻게 수정했는지에 중점을 두고 있습니다. 재작성된 버전은 사용자에게 명확히 설명하고 있으며(500 오류가 줄어든다), 언제 (Elasticsearch로 커밋을 검색할 때) 발생하는지를 명확히 설명하고 있습니다.

여러분의 판단력을 발휘하고 편집된 변경 로그를 읽고 있는 사람의 마음가짐으로 들어가려고 노력하세요. 이 항목이 가치 있는지 추가하나요? 변경 사항이 만들어진 _원인_과 _위치_에 대한 맥락을 제공하나요?