Add empty releases with configurable placeholder text.

[Alexander Karmes]

Is your feature request related to a problem? Please describe.

I'd like a have a possibility to generate an empty changelog entry with a placeholder text like "This release does not include any relevant changes", when parser don't include any commits (omits non relevant once).

Additional context

I'm working on a codebase with several changelogs (public and internal) and parsers are configured to exclude some commit types for public changelog. With current behaviour, git cliff will just omit generating changelog entry all together. And so generated changelog has gaps: v2.1.0 => v2.3.0.

[welcome]

Thanks for opening your first issue at git-cliff! Be sure to follow the issue template! ⛰️

[Orhun Parmaksız]

The problem is that tags are processed as a part of the commit messages - so if you skip a commit then we don't know if where the tag belongs.

As a workaround, if you know the format of the release commits, you can mark them (not to lose the tag) and then later in the template have a condition to check if the release has any commits.

For example, if follow the chore(release): release v0.1.0 format, you can override the group like so:

[git]
commit_parsers = [
  { message = "^chore\\(release\\): ", group = "release_commit" },
]

And then in your template:

[changelog]
body="""
{% for group, commits in commits | group_by(attribute="group") %}
    {% if group == "release_commit" and commits | length == 1 %}
      This release does not include any relevant changes
      {% continue %}
    {% endif %}

<process other commits as usual>
{% endfor -%}
"""

Hope this helps! 🐻

[Alexander Karmes]

Thank you a lot! I've ended up taking your approach, while slightly modifying the proposed solution:

[changelog]
body="""
{% for group_name, group_commits in commits | group_by(attribute="group") %}
    {% if group_name == "release_group" and commits | length == 1 -%}
      This release does not contain any relevant changes.
      {% break %}
    {% endif -%}
   
  <process other commits as usual>
{% endfor %}\n
"""

[Alec Rust]

Wondering if this should be reopened as a bug or request? I've bumped into this too and the behavior is somewhat unexpected.

It would be nice to be able to handle this in the template e.g.

[changelog]
# Changelog body in Slack's "mrkdwn" format
# https://keats.github.io/tera/docs/#introduction
# https://api.slack.com/reference/surfaces/formatting
body = """
{% set has_commits = false %}\
{% for group, commits in commits | group_by(attribute="group") %}\
	{% set has_commits = true %}\
	*{{ group | striptags | trim | upper_first }}*\n\n\
	{% for commit in commits %}\
		• {% if commit.scope %}*({{ commit.scope }})* {% endif %}{{ commit.message | upper_first | trim }}\
		{% if commit.github.pr_number %} \
			(<{{ self::remote_url() }}/pull/{{ commit.github.pr_number }}|#{{ commit.github.pr_number }}>)\
		{% else %} \
			(<{{ self::remote_url() }}/commit/{{ commit.id }}|{{ commit.id | truncate(length=7, end="") }}>)\
		{% endif %}\n\
	{% endfor %}{% if not loop.last %}\n{% endif %}
{% endfor %}\
{% if not has_commits %}Bug fixes and improvements 😉{% endif %}\
{%- macro remote_url() -%}
	https://github.com/{{ remote.github.owner }}/{{ remote.github.repo }}
{%- endmacro -%}
"""

But as you say, git-cliff skips all together in this case.