feat(examples): add GitLab built-in changelog templates

examples/gitlab-detailed.toml

@@ -0,0 +1,111 @@
+# git-cliff ~ configuration file
+# https://git-cliff.org/docs/configuration
+
+# [remote.gitlab]
+# owner = "my-group"
+# repo = "my-project"
+# token = ""
+
+[changelog]
+# A Tera template to be rendered as the changelog's header.
+# See https://keats.github.io/tera/docs/#introduction
+header = """
+# Changelog
+
+All notable changes to this project will be documented in this file.
+"""
+# A Tera template to be rendered for each release in the changelog.
+# See https://keats.github.io/tera/docs/#introduction
+body = """
+{%- macro project_url() -%}
+  {%- set ci_project_url = get_env(name="CI_PROJECT_URL", default="") -%}
+  {%- if ci_project_url != "" -%}
+    {{ ci_project_url }}
+  {%- elif remote.gitlab.api_url and remote.gitlab.owner and remote.gitlab.repo -%}
+    {{ remote.gitlab.api_url | trim_end_matches(pat="/api/v4") }}/{{ remote.gitlab.owner }}/{{ remote.gitlab.repo }}
+  {%- elif remote.gitlab.owner and remote.gitlab.repo -%}
+    https://gitlab.com/{{ remote.gitlab.owner }}/{{ remote.gitlab.repo }}
+  {%- else -%}
+
+  {%- endif -%}
+{%- endmacro -%}
+
+{% macro print_commit(commit) -%}
+  - {% if commit.breaking %}**BREAKING:** {% endif %}{{ commit.message | split(pat="\n") | first | upper_first | trim }} \
+    ([{{ commit.id | truncate(length=7, end="") }}]({{ self::project_url() }}/-/commit/{{ commit.id }}))\
+    {%- if commit.remote.pr_number %} in [!{{ commit.remote.pr_number }}]({{ self::project_url() }}/-/merge_requests/{{ commit.remote.pr_number }}){%- endif -%}\
+    {%- if commit.remote.username %} by @{{ commit.remote.username }}{%- endif -%}\
+    {%- if commit.footers %}\
+      {%- for footer in commit.footers -%}
+        , {{ footer.token }}{{ footer.separator }}{{ footer.value }}
+      {%- endfor -%}
+    {%- endif %}
+{%- endmacro -%}
+
+{% if version %}
+## [{{ version | trim_start_matches(pat="v") }}]({{ self::project_url() }}/-/tags/{{ version }}) - {{ timestamp | date(format="%Y-%m-%d") }}
+{% else %}
+## Unreleased
+{% endif %}
+{% if previous and previous.commit_id and commit_id %}
+[{{ previous.commit_id | truncate(length=7, end="") }}]({{ self::project_url() }}/-/commit/{{ previous.commit_id }})...
+[{{ commit_id | truncate(length=7, end="") }}]({{ self::project_url() }}/-/commit/{{ commit_id }})
+{% endif %}
+{% for group, commits in commits | group_by(attribute="group") %}
+### {{ group | striptags | trim | upper_first }}
+{% for commit in commits %}
+{{ self::print_commit(commit=commit) }}
+{% endfor %}
+
+{% endfor %}
+{%- if gitlab and gitlab.contributors | filter(attribute="is_first_time", value=true) | length != 0 %}
+### New Contributors
+{% for contributor in gitlab.contributors | filter(attribute="is_first_time", value=true) %}
+- @{{ contributor.username }} made their first contribution{%- if contributor.pr_number %} in [!{{ contributor.pr_number }}]({{ self::project_url() }}/-/merge_requests/{{ contributor.pr_number }}){%- endif %}
+{% endfor %}
+{% endif %}
+"""
+# A Tera template to be rendered as the changelog's footer.
+# See https://keats.github.io/tera/docs/#introduction
+footer = """
+<!-- generated by git-cliff -->
+"""
+# Remove leading and trailing whitespaces from the changelog's body.
+trim = true
+
+[git]
+# Parse commits according to the conventional commits specification.
+# See https://www.conventionalcommits.org
+conventional_commits = true
+# Exclude commits that do not match the conventional commits specification.
+filter_unconventional = false
+# An array of regex based parsers for extracting data from the commit message.
+# Assigns commits to groups.
+# Optionally sets the commit's scope and can decide to exclude commits from further processing.
+commit_parsers = [
+  { message = "^[a-z]+\\!:", group = "Breaking Changes" },
+  { body = ".*BREAKING CHANGE", group = "Breaking Changes" },
+  { message = "^feat", group = "Features" },
+  { message = "^fix", group = "Bug Fixes" },
+  { message = "^doc", group = "Documentation" },
+  { message = "^perf", group = "Performance" },
+  { message = "^refactor", group = "Refactor" },
+  { message = "^style", group = "Styling" },
+  { message = "^test", group = "Testing" },
+  { message = "^chore\\(deps.*\\)", skip = true },
+  { message = "^chore\\(pr\\)", skip = true },
+  { message = "^chore\\(pull\\)", skip = true },
+  { message = "^chore\\(release\\): prepare for", skip = true },
+  { message = "^chore|^ci", group = "Miscellaneous Tasks" },
+  { body = ".*security", group = "Security" },
+  { message = "^revert", group = "Revert" },
+]
+# Prevent commits that are breaking from being excluded by commit parsers.
+protect_breaking_commits = true
+# Exclude commits that are not matched by any commit parser.
+filter_commits = false
+# Order releases topologically instead of chronologically.
+topo_order = false
+# Order of commits in each group/release within the changelog.
+# Allowed values: newest, oldest
+sort_commits = "oldest"

examples/gitlab.toml

@@ -0,0 +1,109 @@
+# git-cliff ~ configuration file
+# https://git-cliff.org/docs/configuration
+
+# [remote.gitlab]
+# owner = "my-group"
+# repo = "my-project"
+# token = ""
+
+[changelog]
+# A Tera template to be rendered for each release in the changelog.
+# See https://keats.github.io/tera/docs/#introduction
+body = """
+## What's Changed
+
+{%- if version %} in {{ version | trim_start_matches(pat="v") }}{%- endif -%}
+{% for group, commits in commits | group_by(attribute="group") %}
+### {{ group | striptags | trim | upper_first }}
+{% for commit in commits %}
+  {% if commit.remote.pr_title -%}
+    {%- set commit_message = commit.remote.pr_title -%}
+  {%- else -%}
+    {%- set commit_message = commit.message -%}
+  {%- endif -%}
+  * {% if commit.breaking %}**BREAKING:** {% endif %}{{ commit_message | split(pat="\n") | first | trim }}\
+    {% if commit.remote.username %} by @{{ commit.remote.username }}{%- endif -%}\
+    {% if commit.remote.pr_number %} in \
+      [!{{ commit.remote.pr_number }}]({{ self::project_url() }}/-/merge_requests/{{ commit.remote.pr_number }}) \
+    {%- endif %}
+{%- endfor %}
+
+{%- endfor -%}
+
+{%- if gitlab -%}
+{% if gitlab.contributors | filter(attribute="is_first_time", value=true) | length != 0 %}
+  {% raw %}\n{% endraw -%}
+  ### New Contributors
+{%- endif %}\
+{% for contributor in gitlab.contributors | filter(attribute="is_first_time", value=true) %}
+  * @{{ contributor.username }} made their first contribution
+    {%- if contributor.pr_number %} in \
+      [!{{ contributor.pr_number }}]({{ self::project_url() }}/-/merge_requests/{{ contributor.pr_number }}) \
+    {%- endif %}
+{%- endfor -%}
+{%- endif -%}
+
+{% if version %}
+  {% raw %}\n{% endraw -%}
+  **Tag**: [{{ version }}]({{ self::project_url() }}/-/tags/{{ version }})
+{% endif %}
+
+{%- macro project_url() -%}
+  {%- set ci_project_url = get_env(name="CI_PROJECT_URL", default="") -%}
+  {%- if ci_project_url != "" -%}
+    {{ ci_project_url }}
+  {%- elif remote.gitlab.api_url and remote.gitlab.owner and remote.gitlab.repo -%}
+    {{ remote.gitlab.api_url | trim_end_matches(pat="/api/v4") }}/{{ remote.gitlab.owner }}/{{ remote.gitlab.repo }}
+  {%- elif remote.gitlab.owner and remote.gitlab.repo -%}
+    https://gitlab.com/{{ remote.gitlab.owner }}/{{ remote.gitlab.repo }}
+  {%- else -%}
+
+  {%- endif -%}
+{%- endmacro -%}
+"""
+# Remove leading and trailing whitespaces from the changelog's body.
+trim = true
+# A Tera template to be rendered as the changelog's footer.
+# See https://keats.github.io/tera/docs/#introduction
+footer = """
+<!-- generated by git-cliff -->
+"""
+
+[git]
+# Parse commits according to the conventional commits specification.
+# See https://www.conventionalcommits.org
+conventional_commits = true
+# Exclude commits that do not match the conventional commits specification.
+filter_unconventional = false
+# Split commits on newlines, treating each line as an individual commit.
+split_commits = false
+# An array of regex based parsers to modify commit messages prior to further processing.
+commit_preprocessors = [{ pattern = '\((\w+\s)?#([0-9]+)\)', replace = "" }]
+# An array of regex based parsers for extracting data from the commit message.
+commit_parsers = [
+  { message = "^[a-z]+\\!:", group = "Breaking Changes" },
+  { body = ".*BREAKING CHANGE", group = "Breaking Changes" },
+  { message = "^feat", group = "Features" },
+  { message = "^fix", group = "Bug Fixes" },
+  { message = "^doc", group = "Documentation" },
+  { message = "^perf", group = "Performance" },
+  { message = "^refactor", group = "Refactor" },
+  { message = "^style", group = "Styling" },
+  { message = "^test", group = "Testing" },
+  { message = "^chore\\(deps.*\\)", skip = true },
+  { message = "^chore\\(pr\\)", skip = true },
+  { message = "^chore\\(pull\\)", skip = true },
+  { message = "^chore\\(release\\): prepare for", skip = true },
+  { message = "^chore|^ci", group = "Miscellaneous Tasks" },
+  { body = ".*security", group = "Security" },
+  { message = "^revert", group = "Revert" },
+]
+# Prevent commits that are breaking from being excluded by commit parsers.
+protect_breaking_commits = true
+# Exclude commits that are not matched by any commit parser.
+filter_commits = false
+# Order releases topologically instead of chronologically.
+topo_order = false
+# Order of commits in each group/release within the changelog.
+# Allowed values: newest, oldest
+sort_commits = "newest"

website/docs/integration/gitlab.md

@@ -191,3 +191,33 @@ The will result in:
 - @orhun made their first contribution in #420
 - @cliffjumper made their first contribution in #999
 ```
+
+## GitLab Changelog
+
+If you would like to create release notes tailored for GitLab, you can use the [`gitlab.toml`](https://github.com/orhun/git-cliff/tree/main/examples/gitlab.toml) example.
+
+Since it is already embedded into the binary, you can simply run:
+
+```bash
+git cliff -c gitlab
+```
+
+This will generate a changelog such as:
+
+```md
+## What's Changed in v1.0.0
+
+### Features
+
+- feat(parser): add ability to parse arrays by @orhun in [!123](https://gitlab.com/orhun/git-cliff/-/merge_requests/123)
+
+### New Contributors
+
+- @someone made their first contribution in [!360](https://gitlab.com/orhun/git-cliff/-/merge_requests/360)
+
+**Tag**: [v1.0.0](https://gitlab.com/orhun/git-cliff/-/tags/v1.0.0)
+
+<!-- generated by git-cliff -->
+```
+
+Alternatively, you can use [`gitlab-detailed.toml`](https://github.com/orhun/git-cliff/tree/main/examples/gitlab-detailed.toml) template which provides a detailed changelog with GitLab commit and merge request links.