@wyardley, would you mind doing a documentation review on the website related to configuration and changelog templates pages? I've done significant updates to both with the last two releases and I'm wondering if I missed something or if its clear about the new (& old) functionality. I'm about to do more documentation changes and it would be good to incorporate that feedback in at that time. If you want to add your findings here that would be great. Thanks!

I took a quick look through. Overall, I didn't see anything that stuck out too much. I'm not using this project super actively currently, but hopefully people will create issues or PRs if they do come up with things that are hard to understand.

With Jinja, my high level take is that maybe more presets builtin (or in contrib/), or in-depth examples somewhere in git might be more useful to a lot of people vs. super in-depth docs. Also, having some additional builtin macros for common operations might make doing customization easier. Out of scope of this issue, but just for me as an end user of the module, being able to do more with less complex templating would be the most important thing. For example, having to replicate more or less the same code for breaking vs. non-breaking changes. Of course, one could abstract this more with macros locally, but having some of these components available for use would, I imagine, be really helpful to people. In particular, with a lot of projects in different repos, having to manage a template in each project could get unwieldy when minor updates / improvements are made (this would be a different feature request, but maybe the project could also support retrieving a template from git directly?)

That said, for me, it's probably a matter of style / personal preference, but I think the code examples in this section might be more readable if they were written somewhat like this:

{%- if ctx.changelog_mode == "init" -%}
    {%- include ".changelog_init.md.j2" -%}
{%-  elif ctx.changelog_mode == "update" -%}
    {%- include ".changelog_update.md.j2" -%}
{%- endif -%}

(the dashes to suppress newlines might need to be adjusted slightly -- this is just pseudo-code).

vs how they are now:

{%    if ctx.changelog_mode == "init"
%}{%    include ".changelog_init.md.j2"
%}{#
#}{%  elif ctx.changelog_mode == "update"
%}{%    include ".changelog_update.md.j2"
%}{#
#}{%  endif
%}

I took a quick look through the docs top level, and here are a few things that kind of stuck out (a couple of them may not directly be related to configuration or changelog templates):

• To me, the first section here could be more readable? Not sure if it's the indent or the list, but I just find the formatting a little off.
• I noticed that even though https://python-semantic-release.readthedocs.io/en/latest/troubleshooting.html#increasing-verbosity is within "Troubleshooting", it also has its own left hand menu item? IMO, might be more consistent to have it as a sub-item of troubleshooting in the left menu?
• Numbering and indenting at the end of the description in this section - is it intentional that section 6 shows up in what looks like a quote block, and the the last part (section 6c) shows up like quoted text at various depths vs. how the rest of that section looks?
• Not sure if you are planning on separating out classic angular vs. conventional-commits style (see comment here in the next major? If so, might be worth updating this to clarify, or, if we're keeping a single parser, may be worth saying that we follow conventional commits vs. angular, since we do support things like ! for breaking changes?

I took a quick look through. Overall, I didn't see anything that stuck out too much. I'm not using this project super actively currently, but hopefully people will create issues or PRs if they do come up with things that are hard to understand.

I appreciate you taking the time to help. Thank you for the feedback!

With Jinja, my high level take is that maybe more presets builtin (or in contrib/), or in-depth examples somewhere in git might be more useful to a lot of people vs. super in-depth docs. Also, having some additional builtin macros for common operations might make doing customization easier. Out of scope of this issue, but just for me as an end user of the module, being able to do more with less complex templating would be the most important thing. For example, having to replicate more or less the same code for breaking vs. non-breaking changes. Of course, one could abstract this more with macros locally, but having some of these components available for use would, I imagine, be really helpful to people. In particular, with a lot of projects in different repos, having to manage a template in each project could get unwieldy when minor updates / improvements are made (this would be a different feature request, but maybe the project could also support retrieving a template from git directly?)

That is likely a good point. I have considered a section on the documentation for templates that are from the community that could be added via PR. Unfortunately, It doesn't seem to be a way to do built in macros but I have been adding custom filters to handle common tasks. The newer default templates are using some macros so those will be a starting point. Jinja itself is just complicated syntactically and unfortunately to write out these good templates seems to be just as complex. I would hope to have the default template good for most people and then the customization that is done isn't that much but a copy and modify from the default.

I like the feature idea about pulling from a common template off of git. That would be great for maintainability for sure. Thanks!

Agree to disagree on the jinja styling format. If only the syntax coloring didn't go away with multi-line segements but oh well. This format has been the one that has been the most readable with more complex templates I'm writing now and after the significant whitespace validation, I've been pulling my hair out over with testing, this style format does not leave any whitespace to chance (the - isn't as greedy as one would hope).

• To me, the first section here could be more readable? Not sure if it's the indent or the list, but I just find the formatting a little off.

It was on purpose but will can reconsider.

• I noticed that even though https://python-semantic-release.readthedocs.io/en/latest/troubleshooting.html#increasing-verbosity is within "Troubleshooting", it also has its own left hand menu item? IMO, might be more consistent to have it as a sub-item of troubleshooting in the left menu?

Good catch, I don't know how that happened.

• Numbering and indenting at the end of the description in this section - is it intentional that section 6 shows up in what looks like a quote block, and the the last part (section 6c) shows up like quoted text at various depths vs. how the rest of that section looks?

Yeah that looks awful, I'm sure that wasn't the desired result. Will add it to my list.

• Not sure if you are planning on separating out classic angular vs. conventional-commits style (see comment here in the next major? If so, might be worth updating this to clarify, or, if we're keeping a single parser, may be worth saying that we follow conventional commits vs. angular, since we do support things like ! for breaking changes?

Yes, it is a line item of v10.0.0 after you brought it up originally and likely introducing the name earlier in v9 so that the transition to v10 is just change of defaults. And yes i want to refactor the entire landing page for clarity of setup.

It has been 60 days since the last update on this confirmed issue. @python-semantic-release/team can you provide an update on the status of this issue?

Still in work

It has been 60 days since the last update on this confirmed issue. @python-semantic-release/team can you provide an update on the status of this issue?