-
Notifications
You must be signed in to change notification settings - Fork 255
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
Comments
(side note: using the builtin templating, something like this works, though would probably be cleaner to make a macro / function vs. repeating it) |
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 |
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. |
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. |
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. |
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 |
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 likeCo-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
^M
s 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 likeCo-Authored-By
get inserted in randomly).Also, you could potentially do something like this
(not sure if that would be within
commit
or some other hierarchy) to getfrom the input
(note that type is stripped and scope is now available separately)
The text was updated successfully, but these errors were encountered: