Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

RFC: Add a CHANGELOG.md #1982

Open
wants to merge 1 commit into
base: master
from
Open

RFC: Add a CHANGELOG.md #1982

wants to merge 1 commit into from

Conversation

@jlebon
Copy link
Member

jlebon commented Feb 5, 2020

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.

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](https://github.com/conventional-changelog/standard-version).

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

This comment has been minimized.

Copy link
Member Author

jlebon commented Feb 5, 2020

/hold
This is for after the 2020.1 release.

@jlebon

This comment has been minimized.

Copy link
Member Author

jlebon commented Feb 5, 2020

/hold cancel

@cgwalters

This comment has been minimized.

Copy link
Member

cgwalters commented Feb 5, 2020

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 comment has been minimized.

Copy link
Member

lucab commented Feb 6, 2020

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

This comment has been minimized.

Copy link
Member

ashcrow commented Feb 6, 2020

However we decide to CHANGELOG, I support it 😄

@jlebon

This comment has been minimized.

Copy link
Member Author

jlebon commented Feb 6, 2020

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

This comment has been minimized.

Copy link
Member Author

jlebon commented Feb 6, 2020

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: gitlabhq/gitlabhq@4377ba1. Not sure if that also gets picked up by GitHub's conflict detection and merge.

@jlebon

This comment has been minimized.

Copy link
Member Author

jlebon commented Feb 6, 2020

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

This comment has been minimized.

Copy link
Collaborator

miabbott commented Feb 7, 2020

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 👍 for a CHANGELOG.md

@jlebon

This comment has been minimized.

Copy link
Member Author

jlebon commented Feb 10, 2020

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

This comment has been minimized.

Copy link
Member Author

jlebon commented Feb 10, 2020

See also systemd's NEWS file.

@jlebon

This comment has been minimized.

Copy link
Member Author

jlebon commented Feb 12, 2020

Any more thoughts on this?

@ashcrow

This comment has been minimized.

Copy link
Member

ashcrow commented Feb 12, 2020

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

This comment has been minimized.

Copy link
Collaborator

openshift-ci-robot commented Feb 12, 2020

[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:

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

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Linked issues

Successfully merging this pull request may close these issues.

None yet

6 participants
You can’t perform that action at this time.