allow adding crate name in changelog

[MarcoIeni]

Motivations

Feature requested here.

It would allow to collect the commits of different crates into one changelog, but you would still be able to distinguish which commit belongs to which crate.

Solution

Example:

# Changelog

## crate1 [0.4.5] - 2023-06-09

### Added
- new awesome features

## crate2 [0.1.0] - 2023-06-09

### Added
- new fix

## crate1 [0.4.4] - 2023-06-09

### Added
- new features

This is a bit tricky, because release-plz has one changelog per crate. We have to options:

• change the changelog_include logic to remember which commit each crate belongs to maybe. Still, with this option we skip duplicates and stuff like that. I don't think it's ideal at the moment.
• What if two crates specify the same changelog path? In this case release-plz treats the crates equally (with changelog_include there's a "main" crate, which includes less important crates). We could merge the changelog update of both changelogs and add them to the header of that changelog. This could work and seems reasonable and easy enough.

At the moment, people who want to change how the changelog looks like, configure git-cliff template.

Option 1: use git-cliff

Is adding a crate name in the changelog achievable with git-cliff? Maybe it accepts additional variables?

Option 2: use tera

Do we need to remove git-cliff and use tera by ourselves?
We can put the result given by tera to the top of the CHANGELOG.

This has some benefits:

• remove one dependency (faster compile time)

• people don't need to look at the git-cliff docs, which are big and most features can't be used with release-plz (because they regard parsing git commits, which we do by ourselves)

• if we go this way, we need to write a lot of docs, and document better the default changelog template

Alternatives

Additional context

[XAMPPRocky]

What if two crates specify the same changelog path?

Just on this point, I think I would expect these settings to workspace settings, so it wouldn't be possible for two crates to conflict. I know they're not right now, but I think it would be a good idea to have a workspace setting that sets what kind of changeling you're generating. E.g

scope = "workspace" #  Changelog is generated as one file in workspace, uses workspace level settings
scope = "crate"  # Changelog is generated per crate, uses crate level settings

[MarcoIeni]

Some notes:

Some useful links from git-cliff:
https://github.com/orhun/git-cliff/blob/0eee9cc888468a02bfa0abfd1fdc75691f2d61e6/cliff.toml#L52
https://github.com/orhun/git-cliff/blob/0eee9cc888468a02bfa0abfd1fdc75691f2d61e6/cliff.toml#L19C13-L19C13
https://github.com/orhun/git-cliff/blob/0eee9cc888468a02bfa0abfd1fdc75691f2d61e6/cliff.toml#L64

We can use as a crate name

[MarcoIeni]

Just generated this changelog while working on #1399 😎

# 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]

## `marco-test-two` - [0.4.14](https://github.com/marcoieni/rust-workspace-example/compare/marco-test-two-v0.4.13...marco-test-two-v0.4.14) - 2024-04-16

### Other
- change to 2 and 3

## `marco-test-three` - [0.1.16](https://github.com/marcoieni/rust-workspace-example/compare/marco-test-three-v0.1.15...marco-test-three-v0.1.16) - 2024-04-16

### Other
- change to 2 and 3
- move to subdir

## `marco-test-one` - [0.3.7](https://github.com/marcoieni/rust-workspace-example/compare/marco-test-one-v0.3.6...marco-test-one-v0.3.7) - 2024-04-16

### Other
- move to subdir

configuration:

[[package]] # the double square brackets define a TOML table array
name = "marco-test-two" # name of the package to configure
changelog_path = "./CHANGELOG.md"

[[package]] # the double square brackets define a TOML table array
name = "marco-test-one" # name of the package to configure
changelog_path = "./CHANGELOG.md"

[[package]] # the double square brackets define a TOML table array
name = "marco-test-three" # name of the package to configure
changelog_path = "./CHANGELOG.md"

[changelog]
body = """

## `{{ package }}` - [{{ version | trim_start_matches(pat="v") }}](https://github.com/marcoieni/rust-workspace-example/compare/{{ package }}-v{{ previous.version }}...{{ package }}-v{{ version }}) - {{ 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 %}
"""

[MarcoIeni]

This is now released. Docs here :)