Add a Changelog

[tasansal]

Can we add and maintain a changelog similar to mainstream Dask in the docs?

I can start it, but I am having trouble understanding what changes went into previous versions. @jacobtomlinson Do you have any recommendations on how to do it effectively for recent older versions?

[jacobtomlinson]

The changelog is dask/dask is generated from the git history. See these release instructions.

git log $(git describe --tags --abbrev=0)..HEAD --pretty=format:"- %s \`%an\`_"  > change.md && sed -i -e 's/(#/(:pr:`/g' change.md && sed -i -e 's/) `/`) `/g' change.md

Given that we squash and merge every commit I don't personally get much value out of maintaining changelogs when I can just look at the commit history. Although I do with GitHub showed tags next to the commits on pages like this.

I'm apprehensive to add yet another thing to maintain, especially one that adds extra complexity to the release process. But I'm open to being persuaded that this is a useful thing to do.

Maybe we could just put an empty commit with the tag name on each release like we do in dask/dask to make the commit history more self-explanatory?

[tasansal]

Thanks for the quick resposne @jacobtomlinson

Looking at https://docs.dask.org/en/stable/changelog.html and searching for Kubernetes pretty much doesn't give any useful information.

Looking at commit history works of course, but from a user perspective, it is a lot of overhead everytime I want to see what changed (especially if I haven't looked for a few months).

I think ideally, to keep everything within Dask docs, it would be nice to make that more informative I think. The empty commit with the tag name sounds like a hacky approach :-) surprised to hear dask/dask does that. But another alternative:

In one of my projects I use release-drafter; which basically puts it here in the releases (see here https://github.com/TGSAI/mdio-python/releases). It groups PR titles into categories based on the label in the PR. It is not super coupled to the changelog but at least shows what PRs went into the release.

What do you think?

[jacobtomlinson]

For a project like dask-kubernetes that doesn't change all that often I'm just not convinced it's worth the maintenance overhead.

Given that we squash on merge the commit history just contains a list of all of the PRs, which is basically what a changelog consists of. What value does a changelog.md add over that?

I've used release-drafter in other projects and generally like it, however it's pretty common in Dask projects to release by pushing a tag and I'd prefer not to break convention if we can help it.

[jacobtomlinson]

In #886 I added an automation to create a GitHub Release with release notes. GitHub Releases are now effectively the changelog for the project.