Skip to content

Default changelog template options #952

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
wyardley opened this issue Jun 15, 2024 · 6 comments
Closed

Default changelog template options #952

wyardley opened this issue Jun 15, 2024 · 6 comments
Labels
feature A new feature or a feature request

Comments

@wyardley
Copy link
Contributor

wyardley commented Jun 15, 2024

Description

The default changelog template should provide an easy way for users to get things like the short description (subject of the commit vs. all lines of the commit message), the type, scope, etc. on their own.

This would avoid unexpected behavior like what's seen in the existing python-semantic-release changelog, with things like Co-Authored-By: showing up in the generated markdown, and would make the changelog more readable in cases where there are bulleted lists in the body of the commit, since the changelog itself is also bulleted. It would be nice to be able to get the scope, type, and short message via variables vs. having to do all of this within the template (see #924 for example)

It should also force a specific style of newline (currently, if the commits have ^Ms in them, it seems like they'll end up in the generated changelog).

Use cases

https://github.com/python-semantic-release/python-semantic-release/blob/master/CHANGELOG.md

Avoid confusing stuff like this in the changelog (where the ------ gets converted into something that breaks up the markdown, and where things like Co-Authored-By get inserted in randomly).
image

Also, you could potentially do something like this

* {%-if foo.scope -%}**{{ foo.scope }}**: {%- endif -%}{{ foo.short_message }} ([`{{ commit.commit.hexsha[:7] }}`]({{ commit.commit.hexsha | commit_hash_url }}))

(not sure if that would be within commit or some other hierarchy) to get

* **foobar**: add xyz ([`93e4cca`](https://github.com/someorg/somerepo/commit/93e4ccab200eaca9e0fbaa0fd52be0656b6165c0))

from the input

feat(foobar): add xyz

* Here is a longer set of bulleted or non bulleted descriptions from the body of
   the commit

(note that type is stripped and scope is now available separately)

@wyardley wyardley added the feature A new feature or a feature request label Jun 15, 2024
@wyardley
Copy link
Contributor Author

(side note: using the builtin templating, something like this works, though would probably be cleaner to make a macro / function vs. repeating it)
commit.commit.message.rstrip().partition('\n')[0] }}

@wyardley
Copy link
Contributor Author

wyardley commented Jun 15, 2024

Something like this basically does what I want:

{% for commit in commits %}{% if type_ != "unknown" %}
* {% if commit.scope %}**{{ commit.scope }}**: {% endif %}{{ commit.descriptions[0] }} ([`{{ commit.short_hash }}`]({{ commit.hexsha | commit_hash_url }}))
{% else %}
* {{ commit.commit.message.rstrip().partition('\n')[0] }} ([`{{ commit.short_hash }}`]({{ commit.hexsha | commit_hash_url }}))
{% endif %}{% endfor %}{% endfor %}{% endif -%}

I'm still not sure where the ^Ms are coming from, but will see if I can figure it out.

@wyardley
Copy link
Contributor Author

I will close this one soon, but would be happy to propose an update to the default template (and / or additional examples) if there's interest.

@codejedi365
Copy link
Contributor

There is a lot of different concepts here in this issue. First, I don't believe it will be trivial to "provide options of the default template" to the user. If they don't like the default template, then it is up to them to override it for the time being (maintaining multiple will be complicated).

I personally don't like the default template so I opened #866 to start diving down that path. For some insight, we don't handle squash commits well at all, so I have been working to make that a reality. The maintainer used squash commits when moving to v8 which caused a need to show the entire commit body in the changelog. I aim to support all the merging strategies (merge, squash, rebase) but getting to that point my changelog default improvements have been a bit on hold. The precursors I had in mind were to add changelog testing, add varying merge strategies into test repos, add squash commit parsing, and then improve the default changelogs with things like emojis, heading order based on importance, considerations for defaults of different parser types, etc.

All in all to say, there is a concurrent effort to improve changelog defaults, I will incorporate your ideas and requests as they align to the goal. Please keep providing input into this topic as I didn't think of everything but I wanted to let you know there are other considerations at this time that might slow down changes.

On the topic of full body commits (that have annoying formatting), the commit object that is passed allows folks to grab just the subject line rather than the entire commit body and this is something I have been using in my own projects (the basis for working to improve default changelogs, like yourself). Until I can get the previous items completed and handle squash commits, I won't be changing the default to only specify the subject. My recommendation here is to use the squash commit action when merging dependabot issues and then remove some of that extra fluff or use a template override.

There is also an issue already open for turning off including the commit body but I feel this is already considered with my intended improvements.

I do like the consideration about standardizing newlines across operating systems which I had not considered yet.

@codejedi365 codejedi365 added this to the Better Changelogs milestone Jun 15, 2024
@wyardley
Copy link
Contributor Author

Thanks, this gives a lot of context.

I personally get the use case of squash commits, though for a gitflow type workflow, I always leaned to use linear history in the shared / default branch and do a regular merge commit into trunk. One issue with using all the commit types from a squashed commit is if people misunderstand how to use conventional commits and use multiple types / commits in the same PR when their intent is to create a single type of change.

I think the newline issue is not with different OSes, but I threw up #955 which I think is one way to solve the issue I’m seeing.

It may actually be even simpler than I thought there - will comment / update.

@codejedi365
Copy link
Contributor

codejedi365 commented Jun 15, 2024

One issue with using all the commit types from a squashed commit is if people misunderstand how to use conventional commits and use multiple types / commits in the same PR when their intent is to create a single type of change.

There will be an option to turn it it off but primarily the only issue is between a fix and a feature being mix matched and they wanted a fix level bump. I have more concern for the times when a feature is hidden or a breaking change is hidden inside of a squash. Luckily our regex should find most of the breaking change references but it won't find the type!: syntax. But ultimately I can't really help them in their misunderstanding, I'd rather them learn from the standard.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
feature A new feature or a feature request
Projects
None yet
Development

No branches or pull requests

2 participants