변경로그

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

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

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

## 1.0.0 (2021-01-05)

### 기능 (4개의 변경)

- [기능 1](gitlab-org/gitlab@123abc) by @alice ([병합 요청](gitlab-org/gitlab!123))
- [기능 2](gitlab-org/gitlab@456abc) ([병합 요청](gitlab-org/gitlab!456))
- [기능 3](gitlab-org/gitlab@234abc) by @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로 저장소의 로컬 복사본을 업데이트하세요.
기본 옵션으로 현재 버전(태그를 git describe --tags로 결정)을 위해 변경 로그를 생성하려면:
- 명령 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: 성능 향상
```

사용자 정의 템플릿

기본 템플릿은 GitLab 17.1에서 commit.reference 및 merge_request.reference를 commit.web_url 및 merge_request.web_url로 변경했습니다.

카테고리 섹션은 템플릿을 사용하여 생성됩니다. 기본 템플릿은 다음과 같습니다:

{% if categories %}
{% each categories %}
### {{ title }} ({% if single_change %}1 change{% else %}{{ count }} changes{% end %})

{% each entries %}
- [{{ title }}]({{ commit.web_url }})\
{% if author.credit %} by {{ author.reference }}{% end %}\
{% if merge_request %} ([merge request]({{ merge_request.web_url }})){% end %}

{% end %}

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

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

예를 들어, valid라는 변수가 있을 때, 이 값이 참일 때 “예”를, 그렇지 않을 때 “아니요”를 표시할 수 있습니다:

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

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

each를 사용하여 루핑을 수행하며, 루프 내의 변수는 해당 루프에 대해 범위가 지정됩니다. 루프 내의 현재 값은 변수 태그 {{ it }}를 사용하여 참조합니다. 다른 변수는 현재 루프 값에서 값을 읽습니다. 예를 들어, 다음과 같은 템플릿을 고려해 보십시오:

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

users가 name 필드를 가진 객체 배열이라고 가정하면, 이것은 users의 모든 사용자의 이름을 인쇄합니다.

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

행이 역 슬래시로 끝나면 다음 줄은 무시됩니다. 이를 통해 마크다운 출력에 불필요한 줄 바꿈을 도입하지 않고 여러 줄에 걸쳐 코드를 래핑할 수 있습니다.

{% 및 %}를 사용하는 태그(식 태그로 알려짐)는 바로 뒤에 나오는 줄 바꿈을 소비합니다. 예를 들어, 다음과 같이 처리됩니다:

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

다음과 같이 되는 대신:

---
bar
---

이렇게 되는 대신:

---

bar

---

다음과 같이 구성에서 사용자 정의 템플릿을 지정할 수 있습니다:

---
template: |
  {% if categories %}
  {% each categories %}
  ### {{ title }}

  {% each entries %}
  - [{{ title }}]({{ commit.web_url }})\
  {% if author.credit %} by {{ author.reference }}{% end %}

  {% end %}

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

템플릿을 지정할 때 template: |를 사용해야 하며, template: >는 템플릿 내의 새 줄을 보존하지 않기 때문에 사용해서는 안 됩니다.

템플릿 데이터

commit.web_url 및 merge_request.web_url가 GitLab 17.1에서 소개되었습니다.

최상위 수준에서 다음 변수가 사용 가능합니다:

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.web_url: 예를 들어, https://gitlab.com/gitlab-org/gitlab/-/commit/0a4cdd86ab31748ba6dac0f69a8653f206e5cfc7와 같이 커밋의 URL입니다.

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

이러한 트레일러는 템플릿에서 다음과 같이 참조할 수 있습니다:

{% each entries %}
{% if commit.trailers.Issue %} ([이슈에 대한 링크]({{ commit.trailers.Issue }})){% end %}
{% if commit.trailers.Status %}상태: {{ commit.trailers.Status }}{% end %}
{% end %}

merge_request.reference: 변경 사항을 처음으로 소개한 병합 요청에 대한 참조(예: gitlab-org/gitlab!50063)입니다.
merge_request.web_url: 변경 사항을 처음으로 소개한 병합 요청의 URL(예: https://gitlab.com/gitlab-org/gitlab/-/merge_requests/50063)입니다.
title: 변경 로그 항목의 제목(이는 커밋 제목입니다).

author 및 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-]+)*))?$

이 정규 표현식은 공식 Semantic Versioning 정규 표현식을 기반으로 하며, 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입니다.

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

%%{init: { "fontFamily": "GitLab Sans" }}%% graph LR accTitle: 3개의 커밋 플로차트 accDescr: 커밋 C가 커밋 B를 되돌리는 3개의 커밋 플로우를 보여줍니다. 그러나 이에는 트레일러가 없습니다. A[커밋 A 변경된 변경 로그] --> B[커밋 B 변경된 변경 로그] B --> C[커밋 C 커밋 B를 되돌림]

그러나 되돌린 커밋(커밋 C)도 변경 로그 트레일러를 포함하는 경우, 커밋 A와 C가 모두 변경 로그에 포함됩니다.

%%{init: { "fontFamily": "GitLab Sans" }}%% graph LR accTitle: 3개의 커밋 플로차트 accDescr: 커밋 C가 커밋 B를 되돌리는 3개의 커밋 플로우를 보여줍니다. 그리고 커밋 A와 C 모두 트레일러를 포함하고 있습니다. A[커밋 A 변경된 변경 로그] --> B[커밋 B 변경된 변경 로그] B --> C[커밋 C 커밋 B를 되돌림 변경된 변경 로그]

커밋 B는 건너뜁니다.

변경로그

Git 커밋에 트레일러 추가

변경 로그 생성

API에서

GitLab CLI에서

변경 로그 출력 사용자화

사용자 정의 템플릿

템플릿 데이터

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

되돌린 커밋 처리

관련 주제

도움말

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

도움받기