changelog lint example

[evgeni]

SUMMARY

I think this repo should provide a snippet example how collections can/should lint their changelogs (if they use antsibull at least).

This started as a discussion in #ansible-community with @gundalow and @felixfontein, and I thought writing down my ideas here would be good.

ISSUE TYPE

• Feature Idea

COMPONENT NAME

examples

ADDITIONAL INFORMATION

I think the following two checks should be executed:

1. ensure a PR needs and has a changelog snippet
2. ensure the snippet has valid syntax (antsibull-changelog lint)

Number 2 is rather easy, we have a tool for that. Number 1 is not.

I think we should only enforce changelog entries for parts of the repository (ain't nobody needs a changelog entry when we fix something in .github/), so I think the example should only care about plugins/ (the users then can easily extend that to their needs).

On IRC it was mentioned that new plugins don't need a fragment -- correct, but at the same time nothing validates the version_added entry right now (will that change?) and (as also mentioned on IRC) filter plugins don't have that anyways.

So the simple (lol) logic that we could go for today would be something like:

if (file changed in plugins/ OR file deleted in plugins/ OR file added in plugins/filters/):
    ensure file added in changelogs/fragments/

This won't catch everything, but it's IMHO a good enough 80% solution we should start wirh.

From experience in other projects, there should be a way to ignore this check. Either by adding a "trivial" label or by adding "no issue" somewhere in the commit/PR message. So that will make the above logic a bit more convoluted (at least when implementing it), but at the same time it's not strictly MVP.

[felixfontein]

ansible-test sanity already lints changelog fragments, so 2. is already implemented.

[felixfontein]

About version_added: for modules there's ansible/ansible#69291, but for plugins there's nothing yet.

And it's both test and filter plugins which have neither docs nor version_added. (And of course new roles.)

[gundalow]

Thank you for offering to do this.

This won't catch everything, but it's IMHO a good enough 80% solution we should start wirh.

I'm OK with this.

From experience in other projects, there should be a way to ignore this check.

As you suggest, as GitHub label could work well.

[webknjaz]

Does https://github.com/ansible-collections/collection_template/blob/main/.github/workflows/extra-docs-linting.yml address this?

[evgeni]

If I'm reading the code correctly, no.

It checks the docs for validity, but not whether (or not) a changelog snippet was added for a change.