Feature: Enforce conventional commits and use it to set ArtifactHub.io annotations

[volker-raschek]

Feature

Artifact Hub supports annotations in the Helm Chart file. This allows additional information to be provided to users.

Changes

Changes can be summarized and defined as annotation. This can be archived via artifacthub.io/changes.

annotations:
  artifacthub.io/changes: |
  - kind: added
    description: Cool feature
    links:
    - name: GitHub Issue
      url: https://github.com/issue-url
    - name: GitHub PR
      url: https://github.com/pr-url

This would provide a changelog on ArtifactHub.io. Subscribers to the chart will be informed of the changes in an email sent by ArtifactHub.io when a new version is released. Similar to the changelog on the ArtifactHub.io website. The figure below shows the changelogs provided by the Gitea project.

Forward to GitHub Issues

Furthermore, an URL can be defined to forward users from ArtifactHub.io to GitHub issues if they want to report an issue:

annotations:
  artifacthub.io/links: |
  - name: support
    url: https://github.com/nextcloud/helm/issues

I think this is a great feature for directing users to the right place to report bugs. ArtifactHub.io then displays a special badge on your website with the name Report Issue.

Further annotations

A complete list of supported annotations and the structure can be found on their website.

Implementation

conventional commits

I think the API is clear. The annotations must be set in the chart. Except for the changelog, this should also be quite simple.

For the changelog, however, a diff between the last and current release must be created for each release. Based on the git commits, a changelog must be generated and defined as an annotation in the specified format.

Therefore, I propose introducing conventional commits so that the git changelog can be parsed. I think conventional commits have already become established among many developers and should therefore cause less pain. It is advisable to extend the CI and throw an error if conventional commits are ignored.

I'm completely open-minded when it comes to tools, but based on my experience, I would suggest commitlint. As I mentioned above, my colleagues and I have been using Gitea for quite some time now. The corresponding configuration can be found in the project under .commitlintrc.

add changelog annotation

Currently, I don't know of any tool that can be easily integrated into GitHub Actions to add the annotation. For this reason, there are approaches to solve this using Python, as is done in the x509-certificate exporter, or using a Bash script with the help of yq in the Gitea project.

I have no preference. Once the data basis for conventional commits is available, it should be no problem to generate a changelog from it.

upload changelog

Once the changelog is available, it can also be used optionally to generate a release.

Conclusion

I look forward to your feedback. Please interpret the Implementation section as an example only, to gather ideas and inspiration.

Volker