변경 로그

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

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

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

## 1.0.0 (2021-01-05)

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

- @alice에 의해 [기능 1](gitlab-org/gitlab@123abc) ([병합 요청](gitlab-org/gitlab!123))
- ([병합 요청](gitlab-org/gitlab!456))에 의한 [기능 2](gitlab-org/gitlab@456abc)
- @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로 업데이트합니다.
기본 옵션으로 현재 버전 (태그를 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: 성능 향상
```

사용자 정의 템플릿

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

{% 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.reference }})){% end %}

{% end %}

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

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

예를 들어, valid라는 변수에 대해 다음과 같이 참인 경우 “예”를 표시하고 그렇지 않으면 “아니오”를 표시할 수 있습니다.

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

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

each를 사용하여 반복하고, 루프 내의 변수는 해당 루프에 대해 범위가 지정됩니다. 루프 내의 현재 값에 대한 참조는 변수 태그 {{ it }}를 사용하여 수행됩니다. 변수 태그를 사용하여 중첩된 객체에 액세스할 수 있습니다. 예를 들어, {{ users.0.name }}은 users 변수에서 첫 번째 사용자의 이름을 출력합니다.

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

{ %와 %}을 사용하는 태그 (식 태그라고 함)는 그 뒤의 새 줄을 사용하여 소비합니다. 이는 다음과 같은 것을 의미합니다.

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

다음으로 컴파일됩니다.

---
bar
---

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

---

bar

---

이와 같이 구성에서 사용자 지정 템플릿을 지정할 수 있습니다.

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

  {% each entries %}
  - [{{ title }}]({{ commit.reference }})\
  {% if author.credit %} {{ author.reference }}에 의해{% end %}

  {% end %}

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

템플릿을 지정할 때는 template: |를 사용해야 하며template: >를 사용하면 안 됩니다. 후자는 템플릿의 새 줄을 보존하지 않습니다.

템플릿 데이터

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

categories: 변경 로그 범주마다 하나씩의 개체가 있는 배열입니다.

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

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

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

author.contributor: 저자가 프로젝트 멤버가 아닐 때 true로 설정되는 부울입니다. 그렇지 않으면 false입니다.
author.credit: 저자.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 %}상태: {{ commit.trailers.Status }}{% end %}
{% end %}

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

author 및 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는 되돌릴 커밋의 SHA입니다.

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

graph LR A[커밋 A 변경 로그: 변경됨] --> B[커밋 B 변경 로그: 변경됨] B --> C[커밋 C 커밋 B를 되돌림]

그러나 되돌림 커밋(커밋 C)에도 변경 로그 트레일러가 포함된 경우 커밋 A와 C가 모두 변경 로그에 포함됩니다:

graph LR A[커밋 A 변경 로그: 변경됨] --> B[커밋 B 변경 로그: 변경됨] B --> C[커밋 C 커밋 B를 되돌림 변경 로그: 변경됨]

커밋 B는 건너뜁니다.

변경 로그

Git 커밋에 트레일러 추가

변경 로그 생성

API 사용

GitLab CLI에서

변경 로그 출력 커스터마이징

사용자 정의 템플릿

템플릿 데이터

버전을 추출할 때 태그 형식 사용자 정의

되돌린 커밋 처리

관련 주제

도움말

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

도움받기