Use a release notes generator #965

coilysiren · 2019-11-29T08:15:08Z

j0n3lson · 2019-12-04T23:14:57Z

Hey there,

Been stalking this repo for a while. This one seems interesting to me :)

Would using kubernetes release notes (as suggested) be suitable or did you have something else in mind as well?
https://github.com/kubernetes/release/tree/master/cmd/release-notes

j0n3lson · 2019-12-05T05:34:00Z

I did take a look at release-notes. I think the only draw back is that it requires the GitHub API token. I can't think of a general way (e.g. anyone can publish the release notes with out access to the GitHub token).

Would be nice if release-notes had an option to look at the local git history instead of querying GitHub :(

Thoughts?

saschagrunert · 2019-12-05T08:14:23Z

I did take a look at release-notes. I think the only draw back is that it requires the GitHub API token. I can't think of a general way (e.g. anyone can publish the release notes with out access to the GitHub token).

Would be nice if release-notes had an option to look at the local git history instead of querying GitHub :(

Thoughts?

It parses the PR body for a release-notes block so it will not work without GitHub API access. You just need a read-only token which can be generated by anybody with a valid user account. The tool also supports JSON output, so we could use our own template around it to show-up the notes.

AudriusButkevicius · 2019-12-05T08:54:43Z

Github actions (if we do move to that), provide tokens

j0n3lson · 2019-12-06T04:56:21Z

I'd be happy to take this up then 🤗. Is there any existing documentation on the current release process?

coilysiren · 2019-12-06T19:58:20Z

the current release process?

I do the following steps:

I create the release notes Releases 1.22.2 and 2.0.0 #935
git pull the repo
git checkout the commit mentioned in Releases 1.22.2 and 2.0.0 #935 that corresponds to a particular release version
git tag v...
git push --tags v...
open the release page, for example https://github.com/urfave/cli/releases/tag/v2.0.0
copy the release notes from Releases 1.22.2 and 2.0.0 #935 into the release page https://github.com/urfave/cli/releases/tag/v2.0.0

coilysiren · 2019-12-07T03:00:09Z

@j0n3lson assigned this to you! 🚀

j0n3lson · 2019-12-11T09:58:13Z

I experimented with a few options today:

Experimented with

Nightapes/go-semantic-release

Pros

Easy to configure (stock config file gets you generated CHANGELOG and can create a release.
Manages semantic versioning: Can automatically increment or set a specific value on release
Uses Angular JS Commit format to figure out what the next version should be automatically.
You can set a release version template easily.
Standardized formatting for commit messages!
Supports markdown output
Auto-updates CHANGELOG
Lightweight, written in golang.

Cons

Only supports angular commit message format. I see heavy usage of markdown format so this might be a deal breaker
No support for PRs -- doesn't grab original author or PR#

Kubernetes Release Notes

Pros

Supports PRs
No config needed
Supports markdown output
Auto-updates CHANGELOG (the output of the command is a markdown)

Cons

Does not manage semantic versioning
You need to have a github organization in order to use it (Is urfave already a github org?)
You have to calculate start and end SHAs (e.g. START_SHA=$(git rev-list -n 1 v2.0.0), END_SHA=$(git rev-list -n 1 HEAD)
Not really lightweight (as a lot of dependencies judging by go get ...)

Honorable Mentions

semantic-release/semantic-release

Pros

Supports PRs (example release notes)
Manages semantic version
CI (including Github Actions) out of the box
Support markdown output
Manages Changelog (via plugin)

Cons

Additional dependency on nodejs (the entire project is nodejs) -- Another environmental to manage
Pretty heavy weight
There might be learning curve

I didn't mess around with this because I didn't feel like messing with nodejs which can be wonky to install sometimes.

Summary

If we want to get up and running with generated change logs and releases, Nightapes/go-semantic-release seems like the best fit abut attribution will not be great (no PR support).
Kubernets release can may work but I'd need someone to make urfav a github organization.

j0n3lson · 2019-12-11T19:24:25Z

I think also with Nightapes/go-semantic-release we can easily integrate with the exiting Github Actions setup (I'm no expert here). We'd probably need another action to run on merge and it would:

Fetch Nightapes/go-semantic-release
go mode download dependencies
Generate the change log and commit
Create the release (TODO: test that it release notes == change log)
Push changelog to master

If we go this route we would want:
1.1 Update project documents [Make it work]
1.1.1 Document that we're moving to Angular JS commit format
1.1.2 Document how to manually do a release with go-semantic-release (install, commands, etc)
1.1.3 Distribute a basic githook that checks angular js commit message format (for contributers)
1.1.4 Authorize a bot to check the PR commit messages (something like https://probot.github.io/apps/semantic-pull-requests/)

2.1 Integrate with existing workflow [Make it better]
2.1.1 Create a GitHub action to run on merge and do what I described earlier.

What do you all think?

AudriusButkevicius · 2019-12-11T19:56:03Z

I think the thing we're mostly after is something that compiles release notes, version tagging et al and actually performing the release is somewhat secondary objectives (perhaps I am wrong, as I've been pretty hands off).

My vision of what I would want (but I am not the one making the releases so it's irrelevant to some extent).
Add a status check on PRs forcing them to be tagged skip-release-notes, release-note-bugfix kr release-note-feature, and then something that takes all PR's since last tag/release, filters based on release note tags, and computes small blob of text with PR titles (potentially status check could enforce some more strict PR naming).

Do any of the tools do something like that?

saschagrunert · 2019-12-11T20:13:45Z

The Kubernetes release notes generator tests for a release-notes Code Block which could be part of the pull request template. It supports a somewhat opinionated markdown (sorted by special interest group label, what we don’t have here) and JSON output. So we could write a simple tool around the generator and use the JSON to print the notes into our own template, like labeling PRs by “feature” or “bugfix”.

OTOH we could add another option for the release notes generator to use a template as input, which is an idea I had in the past but did not implemented it right now (because there were no external consumers of this tool.

j0n3lson · 2019-12-11T21:49:12Z

I think the thing we're mostly after is something that compiles release notes, version tagging et al and actually performing the release is somewhat secondary objectives (perhaps I am wrong, as I've been pretty hands off).

Add a status check on PRs forcing them to be tagged skip-release-notes, release-note-bugfix kr release-note-feature

I thought this project might like using labels vs parsing commit messages which seems to agree with what @saschagrunert pointed to. From your description it seems like we'd need something that enforces a rule like: All PRs must have at least one label {skip-release-notes, release-note-bugfix kr release-note-feature}. It would be used at pull request time (and possibly at merge time).

and then something that takes all PR's since last tag/release,

Kubernetes and semantic-release support those use-cases ootb.

filters based on release note tags, and computes small blob of text with PR titles (potentially status check could enforce some more strict PR naming).

I'll look into filtering based on labels in the direction of writing a tool around release-notes as @saschagrunert suggested.

saschagrunert · 2019-12-11T21:58:54Z

From a use case / generating perspective: In the k8s release notes generator you can specify an empty notes block or something like NONE, and the PR gets skipped automatically (no label needed). The good thing is that a maintainer (or the author) could edit the PR if someone says “the note is not appropriate”. Then a re-generation of the notes results in the improved output. So from my point of view it’s easier than relying on the git history.

j0n3lson · 2019-12-21T21:00:23Z

Hey everyone. So I'm a little confused on how to get started/make progress here :(
I think the release-notes tool can already do what @AudriusButkevicius pointed out.

There seems to be two use-cases here:

Generating docs/CHANGELOG.md
Generating release notes (e.g. https://github.com/urfave/cli/releases/tag/v2.0.0)

I guess my main question is would the default output of release-notes (example) be sufficient for both cases? That is, would it be okay if both the CHANGELOG.md and the release notes page both look like the default output of release-notes.

For either case we'd need to do the following to even use the tool:

Adopt the same labels used by kubernetes (e.g. "kind/release-notes" or "kind/bug")
Enforce that a PR has a minimum of (a) a title, (b) a release notes block, and (c) a valid (kubernetes) label. Do this enforcement as a precheck before the PR is sent for review or at merge time (something like https://probot.github.io/apps/semantic-pull-requests/)

The CHANGELOG.md currently follows a simple Added, Removed, Changed format. If you all are really attached to this format then what @saschagrunert suggested (e.g. get notes using release-notes in JSON format and print to template) makes more sense to me.

I'm I thinking about this the right way?

coilysiren · 2019-12-21T21:41:10Z

@j0n3lson

I guess my main question is would the default output of release-notes (example) be sufficient for both cases? That is, would it be okay if both the CHANGELOG.md and the release notes page both look like the default output of release-notes.

The output from release-notes looks just like what I already write, and I already copy from the changelog to the release notes page, so yes 👍👍👍

Adopt the same labels used by kubernetes (e.g. "kind/release-notes" or "kind/bug")

👍 give me the list and I can do it now?

Enforce that a PR has a minimum of (a) a title, (b) a release notes block, and (c) a valid (kubernetes) label. Do this enforcement as a precheck before the PR is sent for review or at merge time (something like https://probot.github.io/apps/semantic-pull-requests/)

This is a distinct task - so I cut a new issue => #1007

The CHANGELOG.md currently follows a simple Added, Removed, Changed format. If you all are really attached to this format then what @saschagrunert suggested (e.g. get notes using release-notes in JSON format and print to template) makes more sense to me.

I would described myself as "fond of" rather than "attached" 🙂 Fully automating the releases is more important to me than keeping the Added, Removed, Changed format.

I'm I thinking about this the right way?

Yep 🚀

saschagrunert · 2019-12-22T17:48:39Z

What if we agree on a set of kinds for every PR, where multiple kinds per PR are possible as well, for example:

kind/bug
kind/cleanup
kind/documentation
kind/feature

Then we could create the notes via the tool, parse the JSON and print it into our own preferred output, like:

Welcome to urfave/cli version x.y.z

# Features
- Adding a shiny new feature which solves all our problems (PR #89317, @lynncyrin)

# Bugfixes
…

coilysiren · 2019-12-22T23:01:34Z

What if we agree on a set of kinds for every PR, where multiple kinds per PR are possible as well, for example

Love this idea ✨

j0n3lson · 2020-01-09T23:35:02Z

I ended up going with @saschagrunert earlier suggestion (support templates in release-tool). I have a PR#1008. With that PR we can specify whatever format we need in the template (and skip bits we don't need like the SIG stuff).

I experimented with wrappers around release-notes as suggested but cried a bit inside because of the duplicate code.

PTAL and let me know what you think!

@lynncyrin Any objection with using the PR template they use in kubernetes (see my PR)? The minimum need is to have either a "release-notes" or "Does this PR introduce a user-facing change?:" block in order to get notes. However, release-notes makes some assumptions about the PR body (I saw some regexps) and it might just be simpler to do as the Romans do here.

coilysiren · 2020-01-10T00:43:46Z

Any objection with using the PR template they use in kubernetes (see my PR)?

No objections, totally ship it!

saschagrunert · 2020-01-10T08:16:34Z

I experimented with wrappers around release-notes as suggested but cried a bit inside because of the duplicate code.

I think I know what you mean 😊

I'm currently working on a tool which uses the release notes parser in a programmatic way, the logic can be mainly found here: https://github.com/kubernetes/release/blob/137f2f6ae4b79c0a02f37517cb147d3bd76e6e9d/cmd/krel/cmd/changelog.go#L131-L199 (might be a source for inspiration)

Edit: Saw the PR in k/release, I think that is the best approach 👍

j0n3lson · 2020-01-15T19:15:49Z

I'm currently working on a tool which uses the release notes parser in a programmatic way, the logic can be mainly found here: https://github.com/kubernetes/release/blob/137f2f6ae4b79c0a02f37517cb147d3bd76e6e9d/cmd/krel/cmd/changelog.go#L131-L199 (might be a source for inspiration)

Yep. That's the one I saw before. I filed issue#1019 on k/release to discuss migrating to the same template-based approach approach as PR#1008.

j0n3lson · 2020-01-15T19:22:06Z

In terms of this issue, the only think left to do is:

Wait for the PR to land in k/release/cmd/release-tool to land
Add a urfave/cli specific template to the repo

Missing anything else?

saschagrunert · 2020-01-16T08:39:53Z

In terms of this issue, the only think left to do is:

Wait for the PR to land in k/release/cmd/release-tool to land

Add a urfave/cli specific template to the repo

Missing anything else?

We can think about adding a GitHub action to generate the notes, but I'm not sure if we want to do that.

coilysiren · 2020-01-16T21:06:13Z

We can think about adding a GitHub action to generate the notes, but I'm not sure if we want to do that.

This definitely sounds like something we'd want to do 👍

j0n3lson · 2020-03-03T06:36:04Z

Finally pushed it. Got busy with taxes and perf and what not. Hopefully can merge it soon :)

j0n3lson · 2020-03-05T08:06:30Z

Just a quick update.

I validated the templating works for both kubernetes use-case and also an arbitrary urfave specific template. I had to valid using my pending pr1148 since release-notes seems to be broken at head due to the template change.
I tested it by pointing at kubernetes/kuberntes but using the urfave template and it produced a good template
I tested by pointing at urfave/cli but got not output becase we are actually missing the release notes block. I had thought it was a header but we actually need to update the template so it has this in the PR body:

```release-notes

```

I should be able to give a demo once my PR get's merged in k8s/release...

zekth · 2021-12-31T13:58:19Z

Github has now automated release note generator: https://docs.github.com/en/repositories/releasing-projects-on-github/automatically-generated-release-notes

meatballhat · 2024-04-29T01:46:38Z

I'd like to call this done since we've been using the GitHub automatic release notes for many releases.

coilysiren added help wanted please help if you can! status/confirmed confirmed to be valid, but work has yet to start kind/maintenance about releasing / CI / Github / other kind of "meta" project maintenance work labels Nov 29, 2019

coilysiren mentioned this issue Nov 29, 2019

Add a pull request template #963

Merged

coilysiren assigned j0n3lson Dec 7, 2019

coilysiren added status/claimed someone has claimed this issue and removed help wanted please help if you can! status/confirmed confirmed to be valid, but work has yet to start labels Dec 7, 2019

coilysiren mentioned this issue Dec 21, 2019

Validate that PRs have a title / release notes / labels #1007

Open

coilysiren mentioned this issue Dec 24, 2019

Create an automated version release system #923

Closed

coilysiren changed the title ~~Use a release notes generator~~ maint: use a release notes generator Dec 24, 2019

j0n3lson mentioned this issue Jan 9, 2020

Add support for using arbitrary Go template when generating markdown. kubernetes/release#1008

Merged

j0n3lson mentioned this issue Jan 10, 2020

Use a more k8s/release friendly PR template. #1035

Merged

meatballhat added this to the Release 2.5.0 milestone Apr 21, 2022

meatballhat changed the title ~~maint: use a release notes generator~~ Use a release notes generator Apr 21, 2022

meatballhat modified the milestones: Release 2.5.0, Release 2.6.0, Release 2.x Apr 26, 2022

meatballhat added the area/v2 relates to / is being considered for v2 label Apr 27, 2024

meatballhat closed this as completed Apr 29, 2024

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Use a release notes generator #965

Use a release notes generator #965

coilysiren commented Nov 29, 2019

j0n3lson commented Dec 4, 2019

j0n3lson commented Dec 5, 2019

saschagrunert commented Dec 5, 2019

AudriusButkevicius commented Dec 5, 2019

j0n3lson commented Dec 6, 2019 •

edited

Loading

coilysiren commented Dec 6, 2019

coilysiren commented Dec 7, 2019

j0n3lson commented Dec 11, 2019

j0n3lson commented Dec 11, 2019

AudriusButkevicius commented Dec 11, 2019

saschagrunert commented Dec 11, 2019 •

edited

Loading

j0n3lson commented Dec 11, 2019

saschagrunert commented Dec 11, 2019 •

edited

Loading

j0n3lson commented Dec 21, 2019

coilysiren commented Dec 21, 2019 •

edited

Loading

saschagrunert commented Dec 22, 2019 •

edited

Loading

coilysiren commented Dec 22, 2019

j0n3lson commented Jan 9, 2020

coilysiren commented Jan 10, 2020

saschagrunert commented Jan 10, 2020 •

edited

Loading

j0n3lson commented Jan 15, 2020

j0n3lson commented Jan 15, 2020

saschagrunert commented Jan 16, 2020

coilysiren commented Jan 16, 2020

j0n3lson commented Mar 3, 2020

j0n3lson commented Mar 5, 2020

zekth commented Dec 31, 2021

meatballhat commented Apr 29, 2024

Use a release notes generator #965

Use a release notes generator #965

Comments

coilysiren commented Nov 29, 2019

j0n3lson commented Dec 4, 2019

j0n3lson commented Dec 5, 2019

saschagrunert commented Dec 5, 2019

AudriusButkevicius commented Dec 5, 2019

j0n3lson commented Dec 6, 2019 • edited Loading

coilysiren commented Dec 6, 2019

coilysiren commented Dec 7, 2019

j0n3lson commented Dec 11, 2019

Experimented with

Nightapes/go-semantic-release

Pros

Cons

Kubernetes Release Notes

Pros

Cons

Honorable Mentions

semantic-release/semantic-release

Pros

Cons

Summary

j0n3lson commented Dec 11, 2019

AudriusButkevicius commented Dec 11, 2019

saschagrunert commented Dec 11, 2019 • edited Loading

j0n3lson commented Dec 11, 2019

saschagrunert commented Dec 11, 2019 • edited Loading

j0n3lson commented Dec 21, 2019

coilysiren commented Dec 21, 2019 • edited Loading

saschagrunert commented Dec 22, 2019 • edited Loading

coilysiren commented Dec 22, 2019

j0n3lson commented Jan 9, 2020

coilysiren commented Jan 10, 2020

saschagrunert commented Jan 10, 2020 • edited Loading

j0n3lson commented Jan 15, 2020

j0n3lson commented Jan 15, 2020

saschagrunert commented Jan 16, 2020

coilysiren commented Jan 16, 2020

j0n3lson commented Mar 3, 2020

j0n3lson commented Mar 5, 2020

zekth commented Dec 31, 2021

meatballhat commented Apr 29, 2024

j0n3lson commented Dec 6, 2019 •

edited

Loading

saschagrunert commented Dec 11, 2019 •

edited

Loading

saschagrunert commented Dec 11, 2019 •

edited

Loading

coilysiren commented Dec 21, 2019 •

edited

Loading

saschagrunert commented Dec 22, 2019 •

edited

Loading

saschagrunert commented Jan 10, 2020 •

edited

Loading