Improve release notes readability

[mloiseleur]

trafficstars

Context

• Current release process is semi-automated, documented here.
• Last year, a new release was published each 3 month
• There are many PRs merged in every release
• There is no known volunteer to work on this matters

=> And so, changelog is quite hard to read. In latest release, v0.13.6, 78 PRs has been merged.

In the past, there were a changelog file. It was removed, see #1754

it creates the problem that whenever we merge a PR, all the other open PRs have a conflict with the changelog file.

Current github action used for release, release-drafter/release-drafter, allows to produce better changelog by configuring and using labels on each PRs. It's not configured and used on external-dns

Edit: It seems they plan to support conventional commit it for the next breaking release.

Proposal

Improve changelog readability by using conventions.

Nowadays, there is a convention about commits.

Those conventional commits improves git history readability and allows to produce changelog based on PR title.

This convention is already suggested by some contributors on this repo who opens their PRs following conventional commit spec. Latest release, v0.13.6, contains 30/78 PRs following this conventions (~38,5%) without any linter or doc about it.

external-dns could adopt conventional commits, enforce it by adding a needed check before merge on it and use a github action aware of this convention (like ncipollo/release-action or requarks/changelog-action) to generate a more readable changelog when releasing a new version.

[mloiseleur]

cc @Raffo @szuecs @njuettner @seanmalloy @johngmyers

[Raffo]

Thank you for opening this @mloiseleur. I would love to offer my point of view: the unit of work on github is a pull request, not a commit. I know this is not conventional git, but it's in practice how people work here. In my experience, as much as we can try to enforce rules on how commits are written or structured, they are often just used as ways to run CI, save half baked unit of work, iterate on things... For bigger chunks of works, it gets hard to keep the commit history really well structured and asking to do so is often a barrier to contribution.

That said, in general I'm not opposed to trying things out and see what we learn. I would prefer if we try proposing rules for the PR title: that would fit our release notes right away and would be easy to lint via a GitHub action. The same can or should apply to PR descriptions in case of breaking changes.

Happy to hear your thoughts.

[mloiseleur]

Yes, conventional commits on the commits inside the PRs are clearly a barrier to contribution.

=> I agree with you, @Raffo, conventional commits in this project would means, in practice, to try, doc and lint on PR title.

[johngmyers]

I like the approach that kops takes: keep a Markdown file for collecting the notes for the next release. Only a limited subset of the PRs warrant a mention in the notes and most of those that do require more than the PR title. The idea is to build them as we go, not require a massive editing job at release time.

[k8s-triage-robot]

The Kubernetes project currently lacks enough contributors to adequately respond to all issues.

This bot triages un-triaged issues according to the following rules:

• After 90d of inactivity, lifecycle/stale is applied
• After 30d of inactivity since lifecycle/stale was applied, lifecycle/rotten is applied
• After 30d of inactivity since lifecycle/rotten was applied, the issue is closed

You can:

• Mark this issue as fresh with /remove-lifecycle stale
• Close this issue with /close
• Offer to help out with Issue Triage

Please send feedback to sig-contributor-experience at kubernetes/community.

/lifecycle stale

[k8s-triage-robot]

The Kubernetes project currently lacks enough active contributors to adequately respond to all issues.

This bot triages un-triaged issues according to the following rules:

• After 90d of inactivity, lifecycle/stale is applied
• After 30d of inactivity since lifecycle/stale was applied, lifecycle/rotten is applied
• After 30d of inactivity since lifecycle/rotten was applied, the issue is closed

You can:

• Mark this issue as fresh with /remove-lifecycle rotten
• Close this issue with /close
• Offer to help out with Issue Triage

Please send feedback to sig-contributor-experience at kubernetes/community.

/lifecycle rotten

[k8s-triage-robot]

The Kubernetes project currently lacks enough active contributors to adequately respond to all issues and PRs.

This bot triages issues according to the following rules:

• After 90d of inactivity, lifecycle/stale is applied
• After 30d of inactivity since lifecycle/stale was applied, lifecycle/rotten is applied
• After 30d of inactivity since lifecycle/rotten was applied, the issue is closed

You can:

• Reopen this issue with /reopen
• Mark this issue as fresh with /remove-lifecycle rotten
• Offer to help out with Issue Triage

Please send feedback to sig-contributor-experience at kubernetes/community.

/close not-planned

[k8s-ci-robot]

@k8s-triage-robot: Closing this issue, marking it as "Not Planned".

In response to this:

The Kubernetes project currently lacks enough active contributors to adequately respond to all issues and PRs.

This bot triages issues according to the following rules:

• After 90d of inactivity, lifecycle/stale is applied
• After 30d of inactivity since lifecycle/stale was applied, lifecycle/rotten is applied
• After 30d of inactivity since lifecycle/rotten was applied, the issue is closed

You can:

• Reopen this issue with /reopen
• Mark this issue as fresh with /remove-lifecycle rotten
• Offer to help out with Issue Triage

Please send feedback to sig-contributor-experience at kubernetes/community.

/close not-planned

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes/test-infra repository.