Skip to main content

Examples

Release-plz comes with a default changelog configuration that adheres to the Keep a Changelog specification. You can customize the changelog format by editing the [changelog] section of the configuration file.

In the following there are some examples of changelog configurations that you can use to take inspiration from. ✨

If you want to contribute your cool template, open a PR! 🙏

info

All examples based on the following Git history:

* df6aef4 (HEAD -> master) feat(cache): use cache while fetching pages
* a9d4050 feat(config): support multiple file formats
* 06412ac (tag: v1.0.1) chore(release): add release script
* e4fd3cf refactor(parser): expose string functions
* ad27b43 (tag: v1.0.0) docs(example)!: add tested usage example
* 9add0d4 fix(args): rename help argument due to conflict
* a140cef feat(parser): add ability to parse arrays
* 81fbc63 docs(project): add README.md
* a78bc36 Initial commit

Release-plz default​

Release-plz default configuration, purely here as a reference.

TOML configuration
[changelog]
header = """# 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]

"""

body = """
## [{{ version | trim_start_matches(pat="v") }}]\
    {%- if release_link -%}\
        ({{ release_link }})\
    {% endif %} \
    - {{ timestamp | date(format="%Y-%m-%d") }}
{% for group, commits in commits | group_by(attribute="group") %}
### {{ group | upper_first }}
    {% for commit in commits %}
        {%- if commit.scope -%}
            - *({{commit.scope}})* {% if commit.breaking %}[**breaking**] {% endif %}\
                {{ commit.message }}\
                {%- if commit.links %} \
                    ({% for link in commit.links %}[{{link.text}}]({{link.href}}) {% endfor -%})\
                {% endif %}
        {% else -%}
            - {% if commit.breaking %}[**breaking**] {% endif %}{{ commit.message }}
        {% endif -%}
    {% endfor -%}
{% endfor %}
"""

commit_parsers = [
  { message = "^feat", group = "added" },
  { message = "^changed", group = "changed" },
  { message = "^deprecated", group = "deprecated" },
  { message = "^fix", group = "fixed" },
  { message = "^security", group = "security" },
  { message = "^.*", group = "other" },
]
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]

### Added

- Support multiple file formats

### Changed

- Use cache while fetching pages

## [1.0.1](https://github.com/orhun/git-cliff-readme-example/compare/v1.0.0...v1.0.1) - 2021-07-18

### Added

- Add release script

### Changed

- Expose string functions

## [1.0.0] - 2021-07-18

### Added

- Add README.md
- Add ability to parse arrays
- Add tested usage example

### Fixed

- Rename help argument due to conflict
Rendered Output

Changelog

All notable changes to this project will be documented in this file. The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

[Unreleased]​

Added​

  • Support multiple file formats

Changed​

  • Use cache while fetching pages

1.0.1 - 2021-07-18​

Added​

  • Add release script

Changed​

  • Expose string functions

[1.0.0] - 2021-07-18​

Added​

  • Add README.md
  • Add ability to parse arrays
  • Add tested usage example

Fixed​

  • Rename help argument due to conflict

Styled and scoped​

TOML configuration
[changelog]
header = """# Changelog

## [Unreleased]

"""

body = """
{% macro print_commit(commit) -%}
    - {% if commit.scope %}*({{ commit.scope }})* {% endif %}\
      {% if commit.breaking %}[**breaking**] {% endif %}\
      {{ commit.message | upper_first }} - \
      ([{{ commit.id | truncate(length=7, end="") }}]({{ remote.link }}/commit/{{ commit.id }}))\
{% endmacro -%}

{% if version %}\
    {% if previous.version %}\
        ## [{{ version | trim_start_matches(pat="v") }}]({{ release_link }})
    {% else %}\
        ## [{{ version | trim_start_matches(pat="v") }}]
    {% endif %}\
{% endif %}\

{% for group, commits in commits
| filter(attribute="merge_commit", value=false)
| unique(attribute="message")
| group_by(attribute="group") %}
    ### {{ group | striptags | trim | upper_first }}
    {% for commit in commits
    | filter(attribute="scope")
    | sort(attribute="scope") %}
        {{ self::print_commit(commit=commit) }}
    {%- endfor -%}
    {% raw %}\n{% endraw %}\
    {%- for commit in commits %}
        {%- if not commit.scope -%}
            {{ self::print_commit(commit=commit) }}
        {% endif -%}
    {% endfor -%}
{% endfor %}\n
"""

commit_parsers = [
  { message = "^feat", group = "<!-- 0 -->⛰️ Features" },
  { message = "^fix", group = "<!-- 1 -->🐛 Bug Fixes" },
  { message = "^doc", group = "<!-- 3 -->📚 Documentation" },
  { message = "^perf", group = "<!-- 4 -->⚡ Performance" },
  { message = "^refactor\\(clippy\\)", skip = true },
  { message = "^refactor", group = "<!-- 2 -->🚜 Refactor" },
  { message = "^style", group = "<!-- 5 -->🎨 Styling" },
  { message = "^test", group = "<!-- 6 -->🧪 Testing" },
  { message = "^chore\\(release\\):", skip = true },
  { message = "^chore: release", skip = true },
  { message = "^chore\\(deps.*\\)", skip = true },
  { message = "^chore\\(pr\\)", skip = true },
  { message = "^chore\\(pull\\)", skip = true },
  { message = "^chore\\(npm\\).*yarn\\.lock", skip = true },
  { message = "^chore|^ci", group = "<!-- 7 -->⚙️ Miscellaneous Tasks" },
  { body = ".*security", group = "<!-- 8 -->🛡️ Security" },
  { message = "^revert", group = "<!-- 9 -->◀️ Revert" },
]

link_parsers = [
  { pattern = "#(\\d+)", href = "{{ remote.link }}/issues/$1" },
  { pattern = "RFC(\\d+)", text = "ietf-rfc$1", href = "https://datatracker.ietf.org/doc/html/rfc$1" },
]
Raw Output
# Changelog

## [Unreleased]

### ⛰️  Features

- feat(config): support multiple file formats ([a9d4050](a9d4050212a18f6b3bd76e2e41fbb9045d268b80))
- feat(cache): use cache while fetching pages ([df6aef4](df6aef41292f3ffe5887754232e6ea7831c50ba5))

## [1.0.1](https://github.com/orhun/git-cliff-readme-example/compare/v1.0.0...v1.0.1)

### 🚜 Refactor

- refactor(parser): expose string functions ([e4fd3cf](e4fd3cf8e2e6f49c0b57f66416e886c37cbb3715))

### ⚙️ Miscellaneous Tasks

- chore(release): add release script ([06412ac](06412ac1dd4071006c465dde6597a21d4367a158))

## [1.0.0] - 2021-07-18

### ⛰️  Features

- feat(parser): add ability to parse arrays ([a140cef](a140cef0405e0bcbfb5de44ff59e091527d91b38))

### 🐛 Bug Fixes

- fix(args): rename help argument due to conflict ([9add0d4](9add0d4616dc95a6ea8b01d5e4d233876b6e5e00))

### 📚 Documentation

- docs(project): add README.md ([81fbc63](81fbc6365484abf0b4f4b05d384175763ad8db44))
- docs(example)!: add tested usage example ([ad27b43](ad27b43e8032671afb4809a1a3ecf12f45c60e0e))
Rendered Output

Changelog

All notable changes to this project will be documented in this file. The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

[Unreleased]​

⛰️ Features​

  • feat(config): support multiple file formats (a9d4050)
  • feat(cache): use cache while fetching pages (df6aef4)

1.0.1​

🚜 Refactor​

  • refactor(parser): expose string functions (e4fd3cf)

⚙️ Miscellaneous Tasks​

  • chore(release): add release script (06412ac)

[1.0.0] - 2021-07-18​

⛰️ Features​

  • feat(parser): add ability to parse arrays (a140cef)

🐛 Bug Fixes​

  • fix(args): rename help argument due to conflict (9add0d4)

📚 Documentation​

  • docs(project): add README.md (81fbc63)
  • docs(example)!: add tested usage example (ad27b43)