diff --git a/examples/gitlab-keepachangelog.toml b/examples/gitlab-keepachangelog.toml new file mode 100644 index 0000000000..29cfa46556 --- /dev/null +++ b/examples/gitlab-keepachangelog.toml @@ -0,0 +1,125 @@ +# git-cliff ~ configuration file +# https://git-cliff.org/docs/configuration + +[changelog] +# A Tera template to be rendered as the changelog's header. +# See https://keats.github.io/tera/docs/#introduction +header = """ +# Changelog\n +All notable changes to this project will be documented in this file. + +The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), +and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).\n +""" +# 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 -%} + +{% if version -%} + ## [{{ version | trim_start_matches(pat="v") }}] - {{ timestamp | date(format="%Y-%m-%d") }} +{% else -%} + ## [Unreleased] +{% endif -%} + +{% for group, commits in commits | group_by(attribute="group") %} + ### {{ group | upper_first }} + {%- for commit in commits %} + - {{ commit.message | split(pat="\n") | first | upper_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.contributors | filter(attribute="is_first_time", value=true) | length != 0 %} + ### 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 %}\n + +{%- if gitlab.contributors | filter(attribute="is_first_time", value=true) | length != 0 %}{% raw %}\n{% endraw -%}{% endif %} + +""" +# A Tera template to be rendered as the changelog's footer. +# See https://keats.github.io/tera/docs/#introduction +footer = """ +{%- 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 -%} + +{% for release in releases -%} + {% if release.version -%} + {% if release.previous.version -%} + [{{ release.version | trim_start_matches(pat="v") }}]: \ + {{ self::project_url() }}/-/compare/{{ release.previous.version }}...{{ release.version }} + {% endif -%} + {% else -%} + [unreleased]: {{ self::project_url() }}/-/compare/{{ release.previous.version }}...HEAD + {% endif -%} +{% endfor %} + +""" +# 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 to modify commit messages prior to further processing. +commit_preprocessors = [ + # Remove issue numbers. + { pattern = '\((\w+\s)?#([0-9]+)\)', replace = "" }, +] +# 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|A]dd", group = "Added" }, + { message = "^[s|S]upport", group = "Added" }, + { message = "^[r|R]emove", group = "Removed" }, + { message = "^.*: add", group = "Added" }, + { message = "^.*: support", group = "Added" }, + { message = "^.*: remove", group = "Removed" }, + { message = "^.*: delete", group = "Removed" }, + { message = "^test", group = "Fixed" }, + { message = "^fix", group = "Fixed" }, + { message = "^.*: fix", group = "Fixed" }, + { message = "^.*", group = "Changed" }, +] +# 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" diff --git a/examples/gitlab.toml b/examples/gitlab.toml new file mode 100644 index 0000000000..22a88dc996 --- /dev/null +++ b/examples/gitlab.toml @@ -0,0 +1,90 @@ +# git-cliff ~ configuration file +# https://git-cliff.org/docs/configuration + +# [remote.gitlab] +# owner = "orhun" +# repo = "git-cliff" +# 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 commit in commits %} + {% if commit.remote.pr_title -%} + {%- set commit_message = commit.remote.pr_title -%} + {%- else -%} + {%- set commit_message = commit.message -%} + {%- 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 -%} + +{%- 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 %} + {% if previous.version %} + **Full Changelog**: {{ self::project_url() }}/-/compare/{{ previous.version }}...{{ version }} + {% endif %} +{% else -%} + {% raw %}\n{% endraw %} +{% 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 = """ + +""" +# An array of regex based postprocessors to modify the changelog. +# Replace the placeholder `` with a URL. +postprocessors = [] + +[git] +# Parse commits according to the conventional commits specification. +# See https://www.conventionalcommits.org +conventional_commits = false +# Exclude commits that do not match the conventional commits specification. +filter_unconventional = true +# 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 = "" }] +# 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" diff --git a/website/docs/integration/gitlab.md b/website/docs/integration/gitlab.md index 3d5c3f119a..36f33b00e8 100644 --- a/website/docs/integration/gitlab.md +++ b/website/docs/integration/gitlab.md @@ -191,3 +191,39 @@ 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) + + +``` + +Alternatively, you can use [`gitlab-keepachangelog.toml`](https://github.com/orhun/git-cliff/tree/main/examples/gitlab-keepachangelog.toml) template which is a mix of GitLab and [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) formats. + +Since it is already embedded into the binary, you can simply run: + +```bash +git cliff -c gitlab-keepachangelog +``` diff --git a/website/docs/templating/examples.md b/website/docs/templating/examples.md index 9c3042f00e..ba58424be6 100644 --- a/website/docs/templating/examples.md +++ b/website/docs/templating/examples.md @@ -469,6 +469,195 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 +#### [GitLab](https://github.com/orhun/git-cliff/tree/main/examples/gitlab.toml) + +
+ Raw Output + +``` +## What's Changed +### Features + * Support multiple file formats by @orhun + * Use cache while fetching pages by @orhun + +## What's Changed in v1.0.1 +### Miscellaneous Tasks + * Add release script by @orhun +### Refactor + * Expose string functions by @orhun + + **Tag**: [v1.0.1](https://gitlab.com/orhun/git-cliff/-/tags/v1.0.1) + +## What's Changed in v1.0.0 +### Breaking Changes + * **BREAKING:** Add tested usage example by @orhun in [!389](https://gitlab.com/orhun/git-cliff/-/merge_requests/389) +### Bug Fixes + * Rename help argument due to conflict by @orhun in [!354](https://gitlab.com/orhun/git-cliff/-/merge_requests/354) +### Documentation + * Add README.md by @orhun +### Features + * Add ability to parse arrays by @orhun + + ### 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) + + +``` + +
+ +
+ Rendered Output + +## What's Changed + +### Features + +- Support multiple file formats by @orhun +- Use cache while fetching pages by @orhun + +## What's Changed in v1.0.1 + +### Miscellaneous Tasks + +- Add release script by @orhun + +### Refactor + +- Expose string functions by @orhun + +**Tag**: [v1.0.1](https://gitlab.com/orhun/git-cliff/-/tags/v1.0.1) + +## What's Changed in v1.0.0 + +### Breaking Changes + +- **BREAKING:** Add tested usage example by @orhun in [!389](https://gitlab.com/orhun/git-cliff/-/merge_requests/389) + +### Bug Fixes + +- Rename help argument due to conflict by @orhun in [!354](https://gitlab.com/orhun/git-cliff/-/merge_requests/354) + +### Documentation + +- Add README.md by @orhun + +### Features + +- Add ability to parse arrays by @orhun + +### 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) + + + +
+ +#### [GitLab + Keep a Changelog](https://github.com/orhun/git-cliff/tree/main/examples/gitlab-keepachangelog.toml) + +
+ Raw Output + +``` +# Changelog + +All notable changes to this project will be documented in this file. + +The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), +and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). + +## Unreleased + +### Features + +- Support multiple file formats ([a9d4050](https://gitlab.com/orhun/git-cliff/-/commit/a9d4050212a18f6b3bd76e2e41fbb9045d268b80)) +- Use cache while fetching pages ([df6aef4](https://gitlab.com/orhun/git-cliff/-/commit/df6aef41292f3ffe5887754232e6ea7831c50ba5)) + +## [1.0.1](https://gitlab.com/orhun/git-cliff/-/tags/v1.0.1) - 2021-07-18 + +[ad27b43](https://gitlab.com/orhun/git-cliff/-/commit/ad27b43e8032671afb4809a1a3ecf12f45c60e0e)...[06412ac](https://gitlab.com/orhun/git-cliff/-/commit/06412ac1dd4071006c465dde6597a21d4367a158) + +### Miscellaneous Tasks + +- Add release script ([06412ac](https://gitlab.com/orhun/git-cliff/-/commit/06412ac1dd4071006c465dde6597a21d4367a158)) + +### Refactor + +- Expose string functions ([e4fd3cf](https://gitlab.com/orhun/git-cliff/-/commit/e4fd3cf8e2e6f49c0b57f66416e886c37cbb3715)) + +## [1.0.0](https://gitlab.com/orhun/git-cliff/-/tags/v1.0.0) - 2021-07-18 + +### Bug Fixes + +- Rename help argument due to conflict ([9add0d4](https://gitlab.com/orhun/git-cliff/-/commit/9add0d4616dc95a6ea8b01d5e4d233876b6e5e00)) in [!354](https://gitlab.com/orhun/git-cliff/-/merge_requests/354) by @orhun + +### Documentation + +- Add README.md ([81fbc63](https://gitlab.com/orhun/git-cliff/-/commit/81fbc6365484abf0b4f4b05d384175763ad8db44)) +- **BREAKING:** Add tested usage example ([ad27b43](https://gitlab.com/orhun/git-cliff/-/commit/ad27b43e8032671afb4809a1a3ecf12f45c60e0e)) in [!389](https://gitlab.com/orhun/git-cliff/-/merge_requests/389) by @orhun + +### Features + +- Add ability to parse arrays ([a140cef](https://gitlab.com/orhun/git-cliff/-/commit/a140cef0405e0bcbfb5de44ff59e091527d91b38)) + + +``` + +
+ +
+ Rendered Output + +# Changelog + +All notable changes to this project will be documented in this file. + +The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), +and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). + +## Unreleased + +### Features + +- Support multiple file formats ([a9d4050](https://gitlab.com/orhun/git-cliff/-/commit/a9d4050212a18f6b3bd76e2e41fbb9045d268b80)) +- Use cache while fetching pages ([df6aef4](https://gitlab.com/orhun/git-cliff/-/commit/df6aef41292f3ffe5887754232e6ea7831c50ba5)) + +## [1.0.1](https://gitlab.com/orhun/git-cliff/-/tags/v1.0.1) - 2021-07-18 + +[ad27b43](https://gitlab.com/orhun/git-cliff/-/commit/ad27b43e8032671afb4809a1a3ecf12f45c60e0e)...[06412ac](https://gitlab.com/orhun/git-cliff/-/commit/06412ac1dd4071006c465dde6597a21d4367a158) + +### Miscellaneous Tasks + +- Add release script ([06412ac](https://gitlab.com/orhun/git-cliff/-/commit/06412ac1dd4071006c465dde6597a21d4367a158)) + +### Refactor + +- Expose string functions ([e4fd3cf](https://gitlab.com/orhun/git-cliff/-/commit/e4fd3cf8e2e6f49c0b57f66416e886c37cbb3715)) + +## [1.0.0](https://gitlab.com/orhun/git-cliff/-/tags/v1.0.0) - 2021-07-18 + +### Bug Fixes + +- Rename help argument due to conflict ([9add0d4](https://gitlab.com/orhun/git-cliff/-/commit/9add0d4616dc95a6ea8b01d5e4d233876b6e5e00)) in [!354](https://gitlab.com/orhun/git-cliff/-/merge_requests/354) by @orhun + +### Documentation + +- Add README.md ([81fbc63](https://gitlab.com/orhun/git-cliff/-/commit/81fbc6365484abf0b4f4b05d384175763ad8db44)) +- **BREAKING:** Add tested usage example ([ad27b43](https://gitlab.com/orhun/git-cliff/-/commit/ad27b43e8032671afb4809a1a3ecf12f45c60e0e)) in [!389](https://gitlab.com/orhun/git-cliff/-/merge_requests/389) by @orhun + +### Features + +- Add ability to parse arrays ([a140cef](https://gitlab.com/orhun/git-cliff/-/commit/a140cef0405e0bcbfb5de44ff59e091527d91b38)) + + + +
+ #### [Minimal](https://github.com/orhun/git-cliff/tree/main/examples/minimal.toml)
diff --git a/website/docs/usage/initializing.md b/website/docs/usage/initializing.md index 607385d722..2e4019cef3 100644 --- a/website/docs/usage/initializing.md +++ b/website/docs/usage/initializing.md @@ -35,6 +35,8 @@ Here are the list of available templates: - [`keepachangelog.toml`](https://github.com/orhun/git-cliff/tree/main/examples/keepachangelog.toml): changelog in [Keep a Changelog format](https://keepachangelog.com/en/1.1.0/). - [`github.toml`](https://github.com/orhun/git-cliff/tree/main/examples/github.toml): changelog in the [GitHub's format](https://docs.github.com/en/repositories/releasing-projects-on-github/automatically-generated-release-notes). - [`github-keepachangelog.toml`](https://github.com/orhun/git-cliff/tree/main/examples/github-keepachangelog.toml): combination of the previous two formats. +- [`gitlab.toml`](https://github.com/orhun/git-cliff/tree/main/examples/gitlab.toml): release notes format tailored for GitLab Releases. +- [`gitlab-keepachangelog.toml`](https://github.com/orhun/git-cliff/tree/main/examples/gitlab-keepachangelog.toml): combination of the previous two formats. - [`detailed.toml`](https://github.com/orhun/git-cliff/tree/main/examples/detailed.toml): changelog that contains links to the commits. - [`minimal.toml`](https://github.com/orhun/git-cliff/tree/main/examples/minimal.toml): minimal changelog. - [`scoped.toml`](https://github.com/orhun/git-cliff/tree/main/examples/scoped.toml): changelog with commits are grouped by their scopes.