변경 로그

Tier: Free, Premium, Ultimate Offering: GitLab.com, Self-Managed, GitLab Dedicated

변경 로그는 커밋 제목과 Git 트레일러를 기반으로 생성됩니다. 변경 로그에 포함되려면 커밋에 특정한 Git 트레일러가 포함되어야 합니다. 변경 로그는 커밋 제목을 기반으로 생성되며, Git 트레일러 유형에 따라 범주화됩니다. 변경 로그 항목에 Merge Request에 대한 링크나 커밋 작성자에 대한 세부 정보와 같은 추가 데이터를 추가할 수 있습니다. 변경 로그 형식은 사용자 정의할 수 있습니다.

기본 변경 로그의 각 섹션은 다음과 같이 버전 번호와 릴리스 날짜를 포함하는 제목을 가지고 있습니다.

## 1.0.0 (2021-01-05)

### 기능 (4개 변경 사항)

- [기능 1](gitlab-org/gitlab@123abc) 작성자: @alice ([Merge Request](gitlab-org/gitlab!123))
- [기능 2](gitlab-org/gitlab@456abc) ([Merge Request](gitlab-org/gitlab!456))
- [기능 3](gitlab-org/gitlab@234abc) 작성자: @steve
- [기능 4](gitlab-org/gitlab@456)

섹션의 날짜 형식은 사용자 정의할 수 있지만, 제목의 나머지 부분은 사용자 정의할 수 없습니다. 새로운 섹션을 추가할 때 GitLab은이러한 제목을 구문 분석하여 파일에 새로운 정보를 배치할 위치를 결정합니다. GitLab은 섹션을 날짜가 아닌 버전에 따라 정렬합니다.

각 섹션은 범주 (예: 기능)별로 정렬된 변경 사항을 포함하며 이러한 섹션의 형식을 변경할 수 있습니다. 섹션 이름은 커밋을 포함하거나 제외하는 데 사용되는 Git 트레일러의 값에서 파생됩니다.

변경 로그의 커밋은 미러에서 작업할 때 검색할 수 있습니다. GitLab 자체도이 기능을 사용합니다. 패치 릴리스는 공개 프로젝트와 개인 보안 미러의 변경 사항을 모두 포함할 수 있기 때문입니다.

Git 커밋에 트레일러 추가

커밋 메시지를 작성할 때 트레일러를 매뉴얼으로 추가할 수 있습니다. 기본 트레일러인 Changelog을 사용하여 기능으로 분류하고 커밋을 포함하려면 다음과 같이 커밋 메시지에 Changelog: feature 문자열을 추가하면 됩니다.

<커밋 메시지 제목>

<커밋 메시지 설명>

Changelog: feature

변경 로그 생성

변경 로그는 API나 GitLab CLI를 사용하여 명령 줄에서 생성됩니다. 변경 로그 출력은 Markdown으로 서식이 지정되며, 사용자 정의할 수 있습니다.

API에서 생성

curl 명령을 사용하여 API를 통해 변경 로그를 생성하려면 API 문서의 변경 로그 파일에 변경 로그 데이터 추가를 참조하십시오.

GitLab CLI에서 생성

glab 버전 1.30.0에 소개되었습니다.

필수 조건:

GitLab CLI 버전 1.30.0 이상을 설치하고 구성했습니다.
귀하의 리포지터리 태그 이름 지정 규칙이 예상되는 태그 형식과 일치합니다.
커밋에 변경 로그 트레일러가 포함되어 있습니다.

변경 로그를 생성하려면:

로컬 리포지터리 사본을 git fetch로 업데이트합니다.
현재 버전을 기준으로 변경 로그를 생성하려면 기본 옵션으로 다음 명령을 실행합니다:
- glab changelog generate 명령을 실행합니다.
- 출력을 파일로 저장하려면 glab changelog generate > <파일명>.md 명령을 실행합니다.
사용자 정의 옵션으로 변경 로그를 생성하려면 glab changelog generate 명령을 실행한 후 원하는 옵션을 추가합니다. 일부 옵션으로는 다음이 있습니다:
- --config-file [문자열]: 프로젝트의 Git 리포지터리에있는 변경 로그 구성 파일의 경로. 이 파일은 프로젝트의 Git 리포지터리에 존재하여야 합니다. 기본값은 .gitlab/changelog_config.yml입니다.
- 커밋 범위:
  - --from [문자열]: 변경 로그 생성에 사용할 커밋 범위의 시작( SHA로)입니다. 이 커밋 자체는 변경 로그에 포함되지 않습니다.
  - --to [문자열]: 변경 로그 생성에 사용할 커밋 범위의 끝( SHA로)입니다. 이 커밋은 디렉터리에 포함됩니다. 기본값은 기본 프로젝트 브랜치의 HEAD입니다.
- --date [문자열]: ISO 8601(2016-03-11T03:45:40Z) 형식의 릴리스의 날짜 및 시간. 기본값은 현재 시간입니다.
- --trailer [문자열]: 커밋을 포함하는 데 사용할 Git 트레일러. 기본값은 Changelog입니다.
- --version [문자열]: 변경 로그를 생성할 버전입니다.

GitLab CLI에서 사용 가능한 매개변수에 대해 자세히 알아 보려면 glab changelog generate --help를 실행하십시오. 정의 및 사용법에 대해서는 API 문서를 참조하십시오.

변경 로그 출력 사용자 정의

변경 로그 출력을 사용자 정의하려면 변경 로그 구성 파일을 편집하고이를 프로젝트의 Git 리포지터리에 커밋하십시오. 이 구성의 기본 위치는 .gitlab/changelog_config.yml입니다. 이 파일은 다음 변수를 지원합니다:

date_format: 새로 추가된 변경 로그 데이터의 제목에 사용되는 strftime 형식의 날짜 형식.
template: 변경 로그 데이터를 생성할 때 사용할 사용자 정의 템플릿.
include_groups: 프로젝트 구성원 여부와 관계없이 기여하는 사용자를 포함해야 하는 그룹 전체 경로 디렉터리. 변경 로그를 생성하는 사용자는 각 그룹에 액세스해야만 크레딧이 부여됩니다.
categories: 변경 로그에서 표시할 범주 이름을 원시 범주 이름에 매핑하는 해시입니다. 변경 로그에 표시되는 이름을 수정하려면 구성 파일에 이러한 줄을 추가하고 필요에 맞게 수정하십시오. 다음 예제는 다음과 같이 범주 제목을 렌더링합니다. ### 기능, ### 버그 수정, ### 성능 향상:
```
---
categories:
  feature: 기능
  bug: 버그 수정
  performance: 성능 향상
```

사용자 정의 템플릿

범주 섹션은 템플릿을 사용하여 생성됩니다. 기본 템플릿은 다음과 같습니다.

{% if categories %}
{% each categories %}
### {{ title }} ({% if single_change %}1개 변경{% else %}{{ count }}개 변경{% end %})

{% each entries %}
- [{{ title }}]({{ commit.reference }})\
{% if author.credit %} 작성자: {{ author.reference }}{% end %}\
{% if merge_request %} ([Merge Request]({{ merge_request.reference }})){% end %}

{% end %}

{% end %}
{% else %}
변경 사항 없음.
{% end %}

{% ... %} 태그는 문장을 위한 것이며, {{ ... }}는 데이터를 출력하기 위해 사용됩니다. 문장은 {% end %} 태그를 사용하여 종료되어야합니다. if와 each 문은 각각 단일 인수가 필요합니다.

예를 들어 valid라는 변수의 경우 값이 true 일 때 “예”를 표시하고, 그렇지 않으면 “아니요”를 표시하려면 다음과 같이합니다.

{% if valid %}
예
{% else %}
아니요
{% end %}

else 사용은 선택 사항입니다. 값이 비어 있지 않은 값이거나 불리언 true 일 때 값이 true로 간주됩니다. 빈 배열 및 해시는 거짓으로 간주됩니다.

each를 사용하여 루핑을 수행하며 루프 내의 변수는 해당 범위로 제한됩니다. 루프 내에서 현재 값을 참조하는 것은 {{ it }} 변수를 사용하는 것입니다. 루프 내에서 변수를 사용할 때 다른 변수는 현재 루프 값에서 값을 읽습니다. 예를 들어 다음과 같은 템플릿을 고려하십시오.

{% each users %}
{{name}}
{% end %}

users가 각각 name 필드를 포함하는 객체 배열인 경우이 명령은 모든 사용자의 이름을 출력합니다.

변수 태그를 사용하면 중첩된 객체에 액세스할 수 있습니다. 예를 들어, {{ users.0.name }}은users 변수에서 첫 번째 사용자의 이름을 출력합니다.

줄 끝에 백 슬래시가있는 경우 다음 줄은 무시됩니다. 이를 통해 Markdown 출력에 불필요한 새 줄을 도입하지 않고 코드를 여러 줄에 걸쳐 래핑할 수 있습니다.

{% 및 %}를 사용하는 태그는 바로 다음에 나오는 새 줄을 소비합니다. 즉, 이것은 이것을 이러한 것으로 컴파일합니다.

---
{% if foo %}
bar
{% end %}
---

다음처럼 컴파일됩니다.

---
bar
---

다음과 같은 것으로 컴파일되지 않습니다.

---

bar

---

사용자 정의 템플릿을 구성할 때는 다음과 같이 template:를 사용하고 template: >를 사용하지 않아야합니다. 후자는 템플릿에서 새 줄을 보존하지 않습니다.

템플릿 데이터

최상위 수준에서 다음 변수를 사용할 수 있습니다.

categories: 각 변경 로그 범주에 대한 객체 배열입니다.

범주 내에서 다음 변수를 사용할 수 있습니다.

count: 이 범주에 있는 항목 수입니다.
entries: 이 범주에 속하는 항목입니다.
single_change: 한 개의 변경사항(true) 또는 여러 변경사항(false)인지를 나타내는 부울 값입니다.
title: 범주의 제목(재매핑된 후)입니다.

항목 내에서 다음 변수를 사용할 수 있습니다(foo.bar에서 bar는 foo의 하위 필드를 의미합니다).

author.contributor: 작성자가 프로젝트 구성원이 아닌 경우 true로 설정되는 부울값이고, 그렇지 않으면 false입니다.
author.credit: 작성자가 true인 경우 또는 include_groups가 구성된 경우, 그리고 작성자가 그룹 중 하나의 구성원인 경우 true로 설정되는 부울값입니다.
author.reference: 커밋 작성자에 대한 참조(예: @alice)입니다.
commit.reference: 커밋에 대한 참조, 예를 들어, gitlab-org/gitlab@0a4cdd86ab31748ba6dac0f69a8653f206e5cfc7입니다.

commit.trailers: 커밋 본문에 있는 모든 Git 트레일러를 포함하는 객체입니다.

이 트레일러들은 템플릿에서 다음과 같이 참조될 수 있습니다.

새로운 인상적인 기능 추가
  
변경 로그: 추가됨
이슈: https://gitlab.com/gitlab-org/gitlab/-/issues/1234
상태: 중요

Changelog, Issue, Status 트레일러는 템플릿에서 다음과 같이 사용될 수 있습니다.

{% each entries %}
{% if commit.trailers.Issue %} ([이슈로 이동]({{ commit.trailers.Issue }})){% end %}
{% if commit.trailers.Status %}Status: {{ commit.trailers.Status }}{% end %}
{% end %}

merge_request.reference: 변경 내용을 처음으로 도입한 Merge Request에 대한 참조(예: gitlab-org/gitlab!50063)입니다.
title: 변경 로그 항목의 제목(이는 커밋 제목입니다).

author 및 merge_request 객체는 데이터를 결정할 수 없는 경우 존재하지 않을 수 있습니다. 예를 들어, 커밋에 대응하는 Merge Request이 없이 커밋을 생성하는 경우, Merge Request이 표시되지 않습니다.

버전 추출 시 태그 형식 사용자 정의

GitLab은 태그 이름에서 의미 있는 버전을 추출하기 위해 정규 표현식(구글의 re2 엔진 및 구문을 사용)을 사용합니다. 기본 정규 표현식은 다음과 같습니다.

^v?(?P<major>0|[1-9]\d*)\.(?P<minor>0|[1-9]\d*)\.(?P<patch>0|[1-9]\d*)(?:-(?P<pre>(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\.(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\+(?P<meta>[0-9a-zA-Z-]+(?:\.[0-9a-zA-Z-]+)*))?$

이 정규 표현식은 공식 시맨틱 버전 정규 표현식에 기반하며, 또한 v로 시작하는 태그 이름도 지원합니다.

프로젝트가 다른 형식의 태그를 사용하는 경우, 다른 정규 표현식을 지정할 수 있습니다. 사용된 정규 표현식은 반드시 다음의 캡처 그룹을 생성해야 합니다. 이러한 캡처 그룹 중 하나라도 빠지면 해당 태그는 무시됩니다.

major
minor
patch

다음 캡처 그룹은 선택 사항입니다.

pre: 지정된 경우, 태그는 무시됩니다. pre 태그를 무시함으로써 릴리스 후보 태그 및 기타 사전 릴리스 태그가 변경 로그를 생성하는 범위를 결정할 때 고려되지 않습니다.
meta: 선택 사항입니다. 빌드 메타데이터를 지정합니다.

이 정보를 이용하여 GitLab은 Git 태그 및 해당 릴리스 버전의 맵을 작성합니다. 그런 다음 각 태그에서 추출된 버전을 기반으로 최신 태그가 무엇인지를 결정합니다.

사용자 정의 정규 표현식을 지정하려면 변경 로그 구성 YAML 파일의 tag_regex 설정을 사용합니다. 예를 들어, 다음 패턴은 version-1.2.3과 같은 태그 이름에 일치하지만 version-1.2와 같은 이름에는 일치하지 않습니다.

---
tag_regex: '^version-(?P<major>\d+)\.(?P<minor>\d+)\.(?P<patch>\d+)$'

정규 표현식이 제대로 작동하는지 테스트하려면 regex101과 같은 웹 사이트를 사용할 수 있습니다. 정규 표현식 구문에 오류가 있으면 변경 로그를 생성할 때 오류가 발생합니다.

되돌린 커밋 처리

되돌린 커밋으로 처리하려면 커밋 메시지에 This reverts commit <SHA> 문자열이 포함되어야 합니다. 여기서 SHA는 되돌릴 커밋의 SHA입니다.

범위에 대한 변경 로그를 생성하는 경우, 해당 범위에서 추가되고 되돌린 커밋이 모두 무시됩니다. 이 예에서 커밋 C는 커밋 B를 되돌립니다. 커밋 C에 다른 트레일러가 없기 때문에 변경 로그에는 커밋 A만 추가됩니다.

%%{init: { "fontFamily": "GitLab Sans" }}%% graph LR A[커밋 A 변경 로그: 변경됨] --> B[커밋 B 변경 로그: 변경됨] B --> C[커밋 C 커밋 B를 되돌림]

그러나 되돌린 커밋(커밋 C)이 또한 변경 로그 트레일러를 포함하는 경우, 커밋 A와 C 둘 다 변경 로그에 포함됩니다.

%%{init: { "fontFamily": "GitLab Sans" }}%% graph LR A[커밋 A 변경 로그: 변경됨] --> B[커밋 B 변경 로그: 변경됨] B --> C[커밋 C 커밋 B를 되돌림 변경 로그: 변경됨]

커밋 B는 건너뜁니다.

변경 로그

Git 커밋에 트레일러 추가

변경 로그 생성

API에서 생성

GitLab CLI에서 생성

변경 로그 출력 사용자 정의

사용자 정의 템플릿

템플릿 데이터

버전 추출 시 태그 형식 사용자 정의

되돌린 커밋 처리

관련 주제

도움말

기능 사용 가능성과 제품 평가판

도움받기