search

redhat-cop / automation-good-practices

Recommended practices for all elements of automation using Ansible, starting with collections and roles, continuing with playbooks, inventories and plug-ins... These good practices are planned to be used by all Red Hat teams interested but can of course be used by others.
265 stars 64 forks source link

Shall we recommend conventional commits for automation changelogs? #88

Open ericzolf opened 1 year ago

ericzolf commented 1 year ago

I've been pitching this approach for a while and there is now a standard: https://www.conventionalcommits.org/en/v1.0.0/ (it's not as powerful as changelog snippets but probably easier to explain/enforce to your usual admin starting to learn Git/Ansible).

it's easier to apply, and a PR/MR-reviewer/approver can more easily correct/improve the commit message before merging than a file somewhere in the repository.

(and you don't have two sources of truth for changes done, but only git log)

djdanielsson commented 1 year ago

I do like the pro of not having 2 locations to note what changes have been made, I think that we probably should be recommending this type of standard. As for this one over others idk, maybe we could give a list of the most used and let each org/user decide what is best for their situation.

felixfontein commented 4 months ago

I disagree with this idea. I think it's important to have two different sources, since the audience of the changelogs are very different:

The information necessary and/or helpful for these audiences is quite different. Especially for collections with modules/plugins in them, I think the information should be separate.

Just think about a change to some module utils that changes the behavior of some function in there due to a refactoring. This is important information for people who work on the code, but it is totally irrelevant to users of the collections - they want to know whether their public API (the module/plugin interfaces) changed.

Of course you could provide both in the same changelog, but in my opinion that would degrade the value of the changelog for users. And typically there are a lot more users of a collection / role than people working on it.

ericzolf commented 4 months ago

I agree with your separation between git log and changelog, but I also think that you can keep the split by using wisely prefixes. I use it in another context at https://github.com/rdiff-backup/rdiff-backup/blob/master/tools/get_changelog_since.sh (this is the script extracting the changelog from the Git log), so Git log lines without prefix are for the developers, Git log lines with prefix (or with specific prefixes) are for the users and hence pulled selectively into the changelog. This works splendidly for my project (says the lazy release manager in me).

I've already used this approach for Ansible customers of mine, and we need to consider that the recommendations are mostly meant for Ansible content creators who are not primarily developers (admins & co), and appreciate slim processes, but by all means, good feedback, we need to make clear the implications.