변경 로그는 커밋 제목과 Git 트레일러를 기반으로 생성됩니다. 변경 로그에 포함되려면 커밋에 특정 Git 트레일러가 포함되어야 합니다. 변경 로그는 커밋 제목에서 생성되며 Git 트레일러 유형별로 분류됩니다. 머지 리퀘스트 링크나 커밋 작성자 세부 정보와 같은 추가 데이터로 변경 로그 항목을 보완할 수 있습니다. 변경 로그 형식은 템플릿으로 사용자 지정할 수 있습니다.

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

## 1.0.0 (2021-01-05)

### Features (4 changes)

- [Feature 1](gitlab-org/gitlab@123abc) by @alice ([merge request](gitlab-org/gitlab!123))
- [Feature 2](gitlab-org/gitlab@456abc) ([merge request](gitlab-org/gitlab!456))
- [Feature 3](gitlab-org/gitlab@234abc) by @steve
- [Feature 4](gitlab-org/gitlab@456)

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

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

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

Git 커밋에 트레일러 추가#

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

Changelog: feature

머지 리퀘스트에 여러 커밋이 있는 경우 첫 번째 커밋에 Changelog 항목을 추가합니다. 이렇게 하면 커밋을 스쿼시할 때 올바른 항목이 생성됩니다.

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

• added: 새 기능
• fixed: 버그 수정
• changed: 기능 변경
• deprecated: 새 사용 중단
• removed: 기능 제거
• security: 보안 수정
• performance: 성능 개선
• other: 기타

변경 로그 만들기#

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

API에서#

curl 명령으로 변경 로그를 생성하는 API를 사용하려면 API 문서의 변경 로그 파일에 변경 로그 데이터 추가를 참조하세요.

GitLab CLI에서#

사전 요구 사항:

• 버전 1.30.0 이상의 GitLab CLI를 설치하고 구성했습니다.
• 저장소의 태그 명명 스키마가 예상되는 태그 명명 형식과 일치합니다.
• 커밋에 변경 로그 트레일러가 포함되어 있습니다.

변경 로그를 생성하려면:

1. git fetch로 저장소의 로컬 복사본을 업데이트합니다.

2. 기본 옵션으로 현재 버전(으로 git describe --tags에 의해 결정됨)의 변경 로그를 생성하려면:

   • glab changelog generate 명령을 실행합니다.
   • 출력을 파일에 저장하려면 glab changelog generate > <filename>.md 명령을 실행합니다.

3. 사용자 지정 옵션으로 변경 로그를 생성하려면 glab changelog generate 명령을 실행하고 원하는 옵션을 추가합니다. 일부 옵션은 다음과 같습니다:

   • --config-file [string]: 프로젝트의 Git 저장소에 있는 변경 로그 구성 파일의 경로. 이 파일은 프로젝트의 Git 저장소에 있어야 합니다. 기본값은 .gitlab/changelog_config.yml입니다.
   • 커밋 범위:
     • --from [string]: 변경 로그를 생성하는 데 사용할 커밋 범위의 시작(SHA로). 이 커밋 자체는 변경 로그에 포함되지 않습니다.
     • --to [string]: 변경 로그를 생성하는 데 사용할 커밋 범위의 끝(SHA로). 이 커밋은 목록에 포함됩니다. 기본값은 기본 프로젝트 브랜치의 HEAD입니다.
   • --date [string]: ISO 8601(2016-03-11T03:45:40Z) 형식의 릴리스 날짜 및 시간. 기본값은 현재 시간입니다.
   • --trailer [string]: 커밋을 포함하는 데 사용할 Git 트레일러. 기본값은 Changelog입니다.
   • --version [string]: 변경 로그를 생성할 버전.

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

변경 로그 출력 사용자 지정#

변경 로그 출력을 사용자 지정하려면 변경 로그 구성 파일을 편집하고 이 변경 사항을 프로젝트의 Git 저장소에 커밋합니다. 이 구성의 기본 위치는 .gitlab/changelog_config.yml입니다.

성능 및 보안상의 이유로 변경 로그 구성 파싱은 2초로 제한됩니다. 구성 파싱으로 인해 시간 초과 오류가 발생하면 구성 크기를 줄이는 것을 고려하세요. 파일은 다음 변수를 지원합니다:

• date_format: 새로 추가된 변경 로그 데이터의 제목에 사용되는 strftime 형식의 날짜 형식.

• template: 변경 로그 데이터를 생성할 때 사용할 사용자 정의 템플릿.

• include_groups: 프로젝트 구성원 여부에 관계없이 기여가 인정되어야 하는 사용자가 포함된 그룹 전체 경로 목록. 변경 로그를 생성하는 사용자는 크레딧을 받으려면 각 그룹에 대한 액세스 권한이 있어야 합니다.

• categories: 원시 범주 이름을 변경 로그에 사용할 이름에 매핑하는 해시. 변경 로그에 표시되는 이름을 변경하려면 구성 파일에 다음 줄을 추가하고 필요에 맞게 편집합니다. 이 예에서는 범주 제목을 ### Features, ### Bug fixes, ### Performance improvements로 렌더링합니다:

  ---
  categories:
    feature: Features
    bug: Bug fixes
    performance: Performance improvements
  

사용자 정의 템플릿#

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

{% 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 %}
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.0.name }}은 users 변수의 첫 번째 사용자 이름을 출력합니다.

줄이 백슬래시로 끝나면 다음 줄 바꿈이 무시됩니다. 이렇게 하면 Markdown 출력에 불필요한 줄 바꿈 없이 여러 줄에 걸쳐 코드를 줄 바꿈할 수 있습니다.

{% 및 %}를 사용하는 태그(표현식 태그라고 함)는 바로 뒤에 오는 줄 바꿈이 있으면 소비합니다. 즉:

---
{% 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 %}
  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.web_url: 커밋에 대한 URL(예: https://gitlab.com/gitlab-org/gitlab/-/commit/0a4cdd86ab31748ba6dac0f69a8653f206e5cfc7).

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

  이 트레일러는 commit.trailers.<name>을 사용하여 참조할 수 있습니다. 예를 들어 다음 커밋을 가정합니다:

  Add some impressive new feature
  
  Changelog: added
  Issue: https://gitlab.com/gitlab-org/gitlab/-/issues/1234
  Status: important
  

  Changelog, Issue, Status 트레일러는 다음과 같이 템플릿에서 액세스할 수 있습니다:

  {% each entries %}
  {% if commit.trailers.Issue %} ([link to issue]({{ commit.trailers.Issue }})){% end %}
  {% if commit.trailers.Status %}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-]+)*))?$

이 정규식은 공식 시맨틱 버전 정규식을 기반으로 하며 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입니다.

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

%%{init: { "fontFamily": "GitLab Sans" }}%%
graph LR
    accTitle: Flowchart of 3 commits
    accDescr: Shows the flow of 3 commits, where commit C reverts commit B, but it contains no trailer
    A[Commit A<br>Changelog: changed] --> B[Commit B<br>Changelog: changed]
    B --> C[Commit C<br>Reverts commit B]

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

%%{init: { "fontFamily": "GitLab Sans" }}%%
graph LR
    accTitle: Flowchart of 3 commits
    accDescr: Shows the flow of 3 commits, where commit C reverts commit B, but both commits A and C contain trailers
    A[Commit A<br><br>Changelog: changed] --> B[Commit B<br><br>Changelog: changed]
    B --> C[Commit C<br>Reverts commit B<br>Changelog: changed]

커밋 B는 건너뜁니다.

관련 항목#

• 리포지토리 API의 변경 로그 관련 엔드포인트.
• GitLab CLI 문서의 glab changelog.