변경 로그

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

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

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

## 1.0.0 (2021-01-05)

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

- @alice에 의해 [기능 1](gitlab-org/gitlab@123abc) ([Merge Request](gitlab-org/gitlab!123))
- [기능 2](gitlab-org/gitlab@456abc) ([Merge Request](gitlab-org/gitlab!456))
- @steve에 의해 [기능 3](gitlab-org/gitlab@234abc)
- [기능 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: 성능 향상
```

### 사용자 정의 템플릿

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

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

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

{% end %}

{% end %}
{% else %}
No changes.
{% end %}

{% ... %} 태그는 문장을 위한 것이며, {{ ... }}는 데이터를 출력하는 데 사용됩니다. 문장은 {% end %} 태그로 종료해야 합니다. ‘if’와 ‘each’ 문장은 각각 하나의 인수가 필요합니다.

예를 들어 ‘valid’라는 변수에 대해 다음과 같이 처리하여 값이 true일 때 “yes”를 표시하고, 그 외에는 “nope”을 표시할 수 있습니다:

{% if valid %}
yes
{% else %}
nope
{% end %}

else 사용은 선택적입니다. 값이 비어있지 않거나 불리언 ‘true’일 때 true로 간주됩니다. 빈 배열과 해시는 false로 간주됩니다.

each를 사용하여 반복 작업을 수행하며, 루프 내의 변수는 해당 루프에 대해 범위가 지정됩니다. 루프 내에서 현재 값을 참조하는 방법은 ‘it’ 변수 태그를 사용하는 것입니다. 루프 내에서 다른 변수의 값은 현재 루프 값에서 읽힙니다. 이러한 템플릿을 예로 들면:

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

‘users’가 ‘name’ 필드를 가진 객체의 배열이라고 가정하면, 이는 ‘users’의 모든 사용자의 이름을 출력할 것입니다.

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

만약 행이 역슬래시로 끝난다면, 다음 줄 바꿈은 무시됩니다. 이를 통해 코드를 여러 줄에 걸쳐 감쌀 수 있으며, Markdown 출력에 불필요한 새 줄을 만들지 않습니다.

{%와 %}를 사용하는 태그는 뒤이어 바로 따라오는 줄 바꿈을 소비합니다(표현 태그라고 함). 이것은 다음을 의미합니다:

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

다음과 같이 컴파일됩니다:

---
bar
---

다음과 같이 컴파일되지 않습니다:

---

bar

---

템플릿을 설정하는 경우 다음과 같이 구성 파일에 사용자 지정 템플릿을 지정할 수 있습니다:

---
template: |
  {% if categories %}
  {% each categories %}
  ### {{ title }}
  
  {% each entries %}
  - [{{ title }}]({{ commit.reference }})\
  {% if author.credit %} by {{ author.reference }}{% end %}
  
  {% end %}
  
  {% end %}
  {% else %}
  No changes.
  {% end %}

템플릿을 지정할 때는 개행을 보존하지 않는 template: > 대신 template: |를 사용해야 합니다.

템플릿 데이터

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

categories: 각 변경 로그 카테고리마다 하나의 객체가 있는 배열입니다.

카테고리에서 다음 변수를 사용할 수 있습니다:

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

항목에서 다음 변수를 사용할 수 있습니다(이때 foo.bar는 ‘bar’가 ‘foo’의 하위 필드라는 의미입니다):

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

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

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

{% 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 13.11에 도입되었습니다.

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과 같은 웹사이트를 사용할 수 있습니다. 정규 표현식 구문이 유효하지 않은 경우, 변경 로그를 생성할 때 오류가 발생합니다. ```

복구된 커밋 처리

GitLab 13.10에서 소개되었습니다.

커밋 메시지가 “This reverts commit "라는 문자열을 포함해야만 복구 커밋으로 취급됩니다. 여기서 `SHA`는 복구할 커밋의 SHA입니다.

범위에 대한 변경 로그를 생성할 때, GitLab은 해당 범위에서 추가 및 복구된 커밋을 무시합니다. 이 예에서는 커밋 C가 커밋 B를 복구합니다. 커밋 C에 다른 트레일러가 없으므로 변경 로그에는 커밋 A만 추가됩니다.

graph LR A[커밋 A Changelog: 변경됨] --> B[커밋 B Changelog: 변경됨] B --> C[커밋 C 커밋 B를 복구함]

그러나 복구 커밋(커밋 C)에도 변경 로그 트레일러가 포함된 경우, 커밋 A와 C가 모두 변경 로그에 포함됩니다.

graph LR A[커밋 A Changelog: 변경됨] --> B[커밋 B Changelog: 변경됨] B --> C[커밋 C 커밋 B를 복구함 Changelog: 변경됨]

커밋 B는 건너뜁니다.

변경 로그

Git 커밋에 트레일러 추가

변경 로그 생성

API를 통해

GitLab CLI를 통해

변경 로그 출력 사용자 정의

템플릿 데이터

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

복구된 커밋 처리

관련 주제

도움말

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

도움받기