Howdy everyone! 
The Red Hat team that works on many of the cloud content collections has been discussing the adoption of the conventional commits format. We wanted to bring this to the attention of the wider community and hear your feedback and any concerns.
For further context, the cloud content collections are outlined in the Collections Overview section of the team handbook.
A brief overview
Conventional commits provide a lightweight structure that makes the type and scope of a change immediately clear from the commit message.
A conventional commit message has the following format:
<type>(<scope>): <description>
[optional body]
[optional footer(s)]
Descriptions should use the imperative: “fix bug” not “fixed bug” or “fixes bug”. This aligns with git’s own internal commit messages (e.g. Merge branch…, Revert “…”), keeping the wording consistent across the entire history.
Here are some examples of commit messages for typical collection changes:
-
feat(ec2_instance): add support for instance bandwidth weighting -
fix(s3_bucket): correct tag comparison when values contain colons -
docs(aws_az_info): clarify availability zone filter behavior -
ci: add integration test for iam_role assume policy
Benefits of adopting conventional commits
Standard commit messages, such as conventional commits, carry more meaning than unstructured ones. A prefix like fix:, feat:, or docs: tells the reader what kind of change was made without opening the diff. This makes it easier to scan project history, understand the purpose of changes, and work across collection repos.
Conventional commits also promote atomicity. Choosing a single type for each commit encourages you to keep commits small and focused on one logical change. Atomic commits simplify code review, make reverts safer, and produce a history that is easier to bisect.
Complementing changelogs
Conventional commits complement changelog fragments, not replace them. Changelog fragments are written for collection users and describe changes in terms of user-visible behavior. On the other hand, commit messages are written for developers and describe what changed in the code. These serve different audiences and should read differently.
Conventional commits can add value as a cross-check. Contributors can find it difficult to know which changelog fragment category to use or if a fragment is needed at all. A conventional commit type provides a straightforward signal. A fix: commit most likely needs a bugfixes fragment. A feat: commit most likely needs a minor_changes fragment. A commit with a BREAKING CHANGE: footer should have a breaking_changes fragment.
A CI check could also flag mismatches. For example, a check might catch a PR with a feat: commit but no changelog fragment. This could help catch missing changelogs before they slip through and reduce the need for manual checks at release time.
Enforcing conventional commits
We also discussed enforcing conventional commits with a CI gate using commitizen.
While it might be a good idea to enforce conventional commits for folks on a dedicated team, we recognize that it might create friction or annoyance for others. With that in mind, it seems like a good idea to be relaxed about enforcement and make the check optional for occasional or first-time contributors.
We could add a bot account that would detect non-conventional commit messages and gently suggest a conventional format, much like how the ansible-documentation-bot encourages PR descriptions.
One thing to note is that repos that use squash merges via Zuul only need to have a conventional commit message in the PR title, not every individual commit. This is how the amazon.aws collection is configured. You can see an example from this PR and the resulting squash commit.
Asking for feedback
What do folks think about this proposal? Are you aware of any other benefits to using conventional commits with Ansible collections or other projects?
What do you think about the idea to add a CI gate for conventional commits? If you’re a contributor to a collection or a collection maintainer, we’d love to hear what you think.
If you maintain or contribute to a collection, have you run into cases where clearer commit messages would have helped?
Do you see any potential issues with adopting conventional commits or have any concerns with collections adopting that format?