RFC: Add a CHANGELOG.md

[jlebon]

Different reasons for this, this website elaborates a bit on them:

https://keepachangelog.com/

But there's more to it from my POV. This will make releases easier, and I think one step closer towards automating it without losing the "human touch" of release notes.

Now, we could make this part of commit messages and e.g. extract them. This is the approach taken by conventional-changelog.

Though I'm not entirely convinced with that approach. For one, commit messages are for a different audience. Second, changelog entries are meant to be much less detailed than commits and may be represented by multiple commits/PRs.

Anyway, if we do this, I think we should start with the easy step first of doing essentially what we already do during releases at PR time. Then we can look at streamlining it if needed.

[jlebon]

/hold This is for after the 2020.1 release.

[jlebon]

/hold cancel

[cgwalters]

Honestly I lean a bit more towards just by default emitting say the commit message title and first paragraph into release notes by default, and expanding where necessary. But not opposed to this, particularly if we can figure out how to make it not a conflict-fest for merges.

[lucab]

This is a recurring conversation that I see popping up in different places. Recently I've been pointed to two different approaches and relevant tools:

1. based on GH pull-request titles, with https://github.com/Songmu/ghch
2. based on explicit changelog snippets, with https://github.com/hawkowl/towncrier

[ashcrow]

However we decide to CHANGELOG, I support it :smile:

[jlebon]

Nice, good to see there's interest! :)

I'll try to write something up with more info later, but essentially: I'm not big on just directly using commit titles and messages, but I'm not against using commit message footers (like the notes: trailer -- see https://github.com/electron/electron/pulls for examples). The approach suggested here will give us the same release notes quality we currently deliver while making releases easier and not having to learn new conventions. We can definitely iterate from there towards something more sophisticated.

One project whose release notes I really like to read is git: https://github.com/git/git/blob/master/Documentation/RelNotes/2.25.0.txt. I probably wouldn't enjoy them as much if they were just semi-cryptic one liners with links to mailing list archives.

[jlebon]

The merge conflict concern is a great point though. Researching quickly, some people seem to have hacked around this by using merge=union in .gitattributes: https://github.com/gitlabhq/gitlabhq/commit/4377ba1c360cf6f4d15e3b5ad2a7ed7bc41f795e. Not sure if that also gets picked up by GitHub's conflict detection and merge.

[jlebon]

My end goal is being able to go from this and just writing up some scripts to make the release process trivial. Once we got that down, we can shove it in a job/bot and have releases just be one click, which means we can release more often. Probably worth looking at the cockpit release scripts for this too.

Related to this of course is getting continuous builds to have faster feedback via cosa & FCOS testing.

[miabbott]

The current release notes for rpm-ostree and ostree are quite good in my opinion, but I understand the desire to move towards something more automated.

I really enjoy reading through the notes for a release and being able to get some of the background for the more important changes. Additionally, seeing your name in the git shortlog output that is included is satisfying, especially when you are not a regular contributor.

So :+1: for a CHANGELOG.md

[jlebon]

I mentioned higher up I'd write more thoughts about this later:

I'm not a fan of using the PR/commit title because in many cases it means nothing for end-users. E.g. just taking the first few from the shortlog of the latest release:

Colin Walters (3):
      treefile: Use ref_from_raw_ptr
      importer: Use /run instead of /var/run
      treefile: Add exclude-packages

Jonathan Lebon (19):
      rust: Wrap parent directory handling for Path
      libpriv/rojig: Fix unref'ing using wrong function
      app/compose: Support multiple --add-metadata-from-json

A couple of those I don't think we even should mention in the CHANGELOG (e.g. the treefile: Use ref_from_raw_ptr, libpriv/rojig: Fix unref'ing using wrong function, rust: Wrap parent directory handling for Path).

Ones we do want to mention, I think it's worth fleshing out more to give more context. E.g. treefile: Add exclude-packages is not much information to go on. We could e.g. take the first couple lines from that commit message, but commit messages are not geared for end-users. Compare e.g. the commit message for that one vs. what we actually wrote in the release notes about that feature:

The treefile now supports a new `exclude-packages` field. This has a similar
effect to specifying exclude= in all the input yum repos. This is useful to
make sure that certain packages never enter the compose, even if recommended via
Recommends. If dependencies are not met because of excluded packages, the
compose fails.

One isn't better than the other. They're just written with different goals in mind. That said, as mentioned earlier, I'm not against using something like tagged commit message footers. If folks prefer we can jump straight to that? Though it'd require some minor scripting to get it working. It also would be harder to give feedback on during PR review since GitHub doesn't allow commenting on commit messages. Another nice thing about the CHANGELOG.md approach is that it provides something nicer to link to and browse for end-users looking for when a feature was added.

There's also a lot of tooling for projects that follow Conventional Commits. And we could try that, but that's a lot more work mentally to adapt to this.

[jlebon]

See also systemd's NEWS file.

[jlebon]

Any more thoughts on this?

[ashcrow]

I agree that just taking commit messages and putting them in the CHANGELOG (or similar) file isn't really ideal. Granted, it's not bad, but those interested in git history can use git. Baring AMAZING git commit messages, those looking for changes in behavior/features would have to look elsewhere (like blogs, full documentation, etc..).

If the main group CHANGELOG.md is meant to target is users then I think starting with a rule that is enforced during PR review is a good start. The template for submitting PRs could be updated with "Is this a new feature/Does this change an existing feature?" or something.

[openshift-ci-robot]

[APPROVALNOTIFIER] This PR is APPROVED

This pull-request has been approved by: ashcrow, jlebon

The full list of commands accepted by this bot can be found here.

The pull request process is described here

Needs approval from an approver in each of these files:

• ~~OWNERS~~ [ashcrow,jlebon]

Approvers can indicate their approval by writing /approve in a comment Approvers can cancel approval by writing /approve cancel in a comment

[openshift-ci-robot]

@jlebon: PR needs rebase.

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.

[openshift-ci[bot]]

@jlebon: The following tests failed, say /retest to rerun all failed tests or /retest-required to rerun all mandatory failed tests:

Test name	Commit	Details	Required	Rerun command
ci/prow/build	95136b015a635a382cfa885d52fd054157b8f432	link	/test build
ci/prow/unit	95136b015a635a382cfa885d52fd054157b8f432	link	/test unit
ci/prow/build-clang	95136b015a635a382cfa885d52fd054157b8f432	link	true	/test build-clang
ci/prow/clang-analyzer	95136b015a635a382cfa885d52fd054157b8f432	link	true	/test clang-analyzer
ci/prow/images	95136b015a635a382cfa885d52fd054157b8f432	link	true	/test images
ci/prow/fcos-e2e	95136b015a635a382cfa885d52fd054157b8f432	link	true	/test fcos-e2e

Full PR test history. Your PR dashboard.

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. I understand the commands that are listed here.

[openshift-ci[bot]]

@jlebon: The following tests failed, say /retest to rerun all failed tests or /retest-required to rerun all mandatory failed tests:

Test name	Commit	Details	Required	Rerun command
ci/prow/build	95136b015a635a382cfa885d52fd054157b8f432	link	/test build
ci/prow/unit	95136b015a635a382cfa885d52fd054157b8f432	link	/test unit
ci/prow/build-clang	95136b015a635a382cfa885d52fd054157b8f432	link	true	/test build-clang
ci/prow/clang-analyzer	95136b015a635a382cfa885d52fd054157b8f432	link	true	/test clang-analyzer
ci/prow/images	95136b015a635a382cfa885d52fd054157b8f432	link	true	/test images
ci/prow/fcos-e2e	95136b015a635a382cfa885d52fd054157b8f432	link	true	/test fcos-e2e
ci/prow/kola-upgrade	95136b015a635a382cfa885d52fd054157b8f432	link	true	/test kola-upgrade

Full PR test history. Your PR dashboard.

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. I understand the commands that are listed here.

[jlebon]

Closing this. A lot of these ideas are implemented in other projects like https://github.com/coreos/coreos-installer/ and https://github.com/coreos/ignition. We can look to those if we want to have some kind of in-tree changelog.