Support outputting a changelog in reStructuredText

[jtpavlock]

Description

As the title states, it would be convenient for use with sphinx documentation to be able to output the changelog in rst format.

Possible Solution

This seems like it should be a configuration option versus a commandline option.

[Lee-W]

It might be related to this PR https://github.com/commitizen-tools/commitizen/pull/376. I don't think we'll explicitly support reStructuredText but make the template customizable instead. This is still under discussion.

[woile]

I find it a bit hard, because the "magic" is tied to markdown. Commitizen can detect your latest version by reading the titles (#), without affecting extra text nor your old changelog. By doing it this way, you can integrate commitizen into a project with an existing changelog (but only with markdown).

https://github.com/commitizen-tools/commitizen/blob/aa0debe9ae5939afb54de5f26c7f0c395894e330/commitizen/changelog.py#L181-L186

https://github.com/commitizen-tools/commitizen/blob/aa0debe9ae5939afb54de5f26c7f0c395894e330/commitizen/changelog.py#L221-L226

It would involve quite some refactoring unfortunately.

An alternative could be running a markdown to rst as an step in a github action.

[jtpavlock]

Commitizen can detect your latest version by reading the titles (#), without affecting extra text nor your old changelog.

Can I ask what the reason for this is as opposed to getting the project version programmatically via package inspection? Is this just a fallback?

[woile]

We can't inspect a markdown file.

Let's say you didn't generate a changelog for the last 2 releases. What can we do to detect which was the latest release created? We go and read the changelog file.

Let's also say, the last release in the changelog, has been modified by the user. So you cannot replace it. How do you detect the latest release created, and update the changelog leaving the previous releases untouched?

Because we are tied to markdown, we just compare against any text starting with one or more #, and we insert the incremented missing chunk of changelog, before that.

Also:

• We must avoid lines that may contain a mention to the latest release. Example:

# Changelog

Latest release: 1.4.0

## 1.4.0
...

In the end the current solution seemed to be covering our use cases fine so far 😅

If there are better solutions I'd like to know more.

[jtpavlock]

One solution could be to only generate the changelog for the latest release by default. Then, if someone wants to generate a changelog for all releases, have that be a command option. Users should only ever be generating a changelog for more than the most recent version of their project once, at the time of adoption of this tool.

If the user only wanted a changelog for the last X number of versions, then it would be an easy cut/paste job from the command generated changelog. Again, this scenario should only ever happen once in a project's lifetime, so not a big deal.

It doesn't seem you'd need to be inspecting any changelog files with this all or one generation approach, and then could theoretically support any number of file types, given the changelog output itself is configurable.

[woile]

That makes a lot of sense and would simplify things a lot. Either generate all or latest, right?. If you need specific range you can use cz changelog 0.2.0..0.4.0 and that would cover all the cases. Is a trade-off over more manual work (sometimes), vs making it more flexible to support other formats.

One good thing about the detection of the title is that you can have a bunch of text before the changelog (like the recommendation of keepachangelog before start listing the changes). How could we achieve that?

[jtpavlock]

One good thing about the detection of the title is that you can have a bunch of text before the changelog (like the recommendation of keepachangelog before start listing the changes). How could we achieve that?

A couple of options come to mind, but all require searching the changelog file:

1. Search for a line with a regex match of the configured release title e.g. v\d\.\d\.\d or something
2. Use some sort of delineator to split the header from the rest of the changelog like a comment or a dashed line.
3. Instead of searching for # title for markdown, just include the ability to now search for the header in rst format if in an rst file.