search

ansible-collections / community.kubernetes

Kubernetes Collection for Ansible
https://galaxy.ansible.com/community/kubernetes
GNU General Public License v3.0
265 stars 106 forks source link

Figure out the best way to handle CHANGELOG updates #40

Closed geerlingguy closed 4 years ago

geerlingguy commented 4 years ago
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:

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:

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
COMPONENT NAME

CHANGELOG.md

ADDITIONAL INFORMATION

N/A

geerlingguy commented 4 years ago

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

geerlingguy commented 4 years ago

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 commented 4 years ago

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

imjoseangel commented 4 years ago

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 commented 4 years ago

See: https://github.com/ansible-collections/overview/issues/18#issuecomment-637718686

felixfontein commented 4 years ago

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 commented 4 years ago

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: https://github.com/ansible-collections/overview/issues/18#issuecomment-643785507

geerlingguy commented 4 years ago

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

antsibull-changelog release --version 0.9.0 --date 2020-02-05
geerlingguy commented 4 years ago

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: