Figure out the best way to handle CHANGELOG updates

[geerlingguy]

SUMMARY

Ansible core uses 'changelog fragments' (see docs for creating a changelog fragment) to make building a release-specific CHANGELOG file easier.

That might be overkill for a project with the reduced scope we have in this collection, but we still need a way to make sure all relevant changes (e.g. anything other than a grammar fix to the README or an adjustment to CI to fix failing tests) are encapsulated in the CHANGELOG file.

Right now, there are already two new module additions that are not documented in the CHANGELOG, but should be:

• k8s_log: Add k8s_log module #16
• k8s_exec: Add k8s_exec module to execute command through the API #14

Ideally, we would have some mechanism by which the CHANGELOG could be updated on a per-PR basis (and this would be one of the gates that would have to be passed before merging it)—but as with any other project where it's a requirement, one of the hardest parts is making sure users don't have to babysit their PRs while other ones come in and cause merge conflicts in the CHANGELOG file—there's no better way to discourage contributors than to make them do annoying tasks over and over again while their PR rots.

We could use a similar changelog generator that ansible/ansible uses, with sections including:

• major_changes
• minor_changes
• deprecated_features
• removed_features
• bugfixes
• known_issues

But we would need to integrate reno (or is it https://github.com/openstack/reno ?) into the release process (see more reno docs).

ISSUE TYPE

• Feature Idea

COMPONENT NAME

CHANGELOG.md

ADDITIONAL INFORMATION

N/A

[geerlingguy]

Another (perhaps simpler) option would be towncrier: https://towncrier.readthedocs.io/en/actual-freaking-docs/

[geerlingguy]

Also it was suggested we might be able to rely on https://github.com/ansible/ansible/blob/devel/packaging/release/changelogs/changelog.py — maybe that could be made more generic / abstracted into the community space, so it can be used by all Collections.

[webknjaz]

FYI I have a GitHub App for enforcing towncrier change fragments in PRs (example check: tox-dev/tox#1529 (comment)). src: https://github.com/sanitizers/chronographer-github-app

[imjoseangel]

Also it was suggested we might be able to rely on https://github.com/ansible/ansible/blob/devel/packaging/release/changelogs/changelog.py — maybe that could be made more generic / abstracted into the community space, so it can be used by all Collections.

Today after a PR under Community General Collections I was wondering about this. Why not using by default the changelog in all the projects and even including them in the build as mandatory.

What do you think guys?

[geerlingguy]

See: ansible-collections/overview#18 (comment)

• Install via pip: https://pypi.org/project/antsibull-changelog/
• Docs: https://github.com/ansible-community/antsibull-changelog/blob/master/docs/changelogs.rst
• Syntax example: https://github.com/ansible-community/antsibull-changelog/blob/master/docs/changelog.yaml-format.md

[felixfontein]

The syntax example is for the generated changelog.yaml; it's mostly aimed at people who want to use another changelog generator and want to adjust it / add a plugin which outputs changelog.yaml so ACD can consume it.

[geerlingguy]

ansible-test sanity now includes a changelog fragment linting sanity check: if changelogs/fragments/ exists and contains files, these will be linted with antsibull-changelog. (If changelogs/config.yaml does not exist when fragments are found, the test will fail.)

See: ansible-collections/overview#18 (comment)

[geerlingguy]

It looks like I can create fragments and backdate releases with:

antsibull-changelog release --version 0.9.0 --date 2020-02-05

[geerlingguy]

Work on this is in #40 — I have a few questions posted about how the changelog generator works, as I had a couple quirks when I was trying to build the changelogs:

• Getting YAMLLoadWarnings when generating changelogs ansible-community/antsibull-changelog#17
• New modules incur weird looking new section 'New Modules' ansible-community/antsibull-changelog#18
• Is generated changelog supposed to end up inside changelogs dir? ansible-community/antsibull-changelog#19
• Allow markdown? ansible-community/antsibull-changelog#20