Is there a way to add a release changelog without doing a dual commit?

[marcosnils]

We recently introduced a new changelog tracking process #5408 which, in summary, proposes the following workflow:

1. Create a branch
2. Add your code (commit)
3. Create a PR
4. Perform changie new and manually add the PR # from previous step
5. Add changie file (commit)

I'm wondering if this somehow could be simplified since steps 4 and 5 could be forgotten and/or have typos given that it's best effort.

For example, instead of specifying the PR number, we could specify the commit where the changie file was added. This way, the dual commit is not required and we could also quite easily add a linting process which checks that all changie files have the current commit in a PR before merging to main.

cc @gerhard

[marcosnils]

from @miniscruff in discord:

I usually recommend using an issue rather than a pull request. As the change relates to a user in the form of an issue. Not the implementation details in a pull request.

[gerhard]

While we could switch to referencing issues instead of PRs, we know that there isn't always an issue for a change that we want in the release notes. This would require us to always create an issue before we could reference a change in the release notes.

We also know that for every change, there is a PR. While this is not convenient (we don't know the PR number before we open the PR), the following makes me think that PRs are the right ones to reference in release notes:

• the bulk of discussions happen as comments on a PR
• gh CLI defaults to PRs in release notes
• all popular projects that we use - e.g. https://github.com/moby/buildkit/releases/tag/v0.12.0, https://github.com/goreleaser/goreleaser/releases/tag/v1.19.2, etc. - reference PRs in relese notes

These steps sound right to me:

1. Create a new branch on your repo fork
2. Add the changes & push to your repo fork
3. Open a draft PR against dagger/dagger (checks will not be triggered)
4. If required (not all PRs need to be present in release notes) run changie new and modify the commit with the new fragment
5. Force push the modified commit
6. Mark the PR as ready for review (this will kick off the checks)

Let's take #5343 for example @marcosnils. Would you have preferred to create an issue before you could reference it in the release notes?

I am pretty sure that referencing commits in changie new would not work for us since squash & merge PRs, meaning that a new commit is created at merge time.

What workflow would others prefer? cc @vito @sipsma @helderco @TomChv @grouville @aluzzardi @jlongtine

[vito]

@gerhard That workflow sounds natural to me. I personally prefer release notes to link to PRs, since it makes it easier to snoop around and build up more context.

Slight correction: draft PRs will run checks, though I don't think this takes away from your point at all.

I do have a feeling we'll forget to run changie a lot, at least while the muscle memory builds. It would be pretty great if there was a check that would fail until you run changie new or add some kind of label indicating that it can skip the changelog.

[marcosnils]

Let's take #5343 for example @marcosnils. Would you have preferred to create an issue before you could reference it in the release notes?

no, not really. I'd find that more annoying that the original discussion flow personally.

I do have a feeling we'll forget to run changie a lot, at least while the muscle memory builds. It would be pretty great if there was a check that would fail until you run changie new or add some kind of label indicating that it can skip the changelog.

That's another concern of why I started this discussion. It'll definitely take time to build muscle memory and without finding a way to enforce it, we never know how effort it'll take us to get to a good enough state 🙏. I like @vito's idea to make it mandatory by default.

Another idea that comes to my mind to help with SDK releases is to somehow be able generate multiple release notes from the same repo. Not sure if the use-case is supported @miniscruff

[miniscruff]

Changie has a workflow to check for missing fragments here https://github.com/miniscruff/changie/blob/main/.github/workflows/changelog-check.yml

In terms of multiple releases from one repo there is a new issue about using a projects keyword for that. Right now the options are to configure each project separately. Or to bundle them into one release separated by components.

Open to feedback on that feature to build it properly as needed.