Quality of the release notes/commit descriptions

[mbg]

Firstly, a thank you to the contributors and maintainers of the actions in this repository! I use the setup action all the time for all of my Haskell projects. It's really nice to have and works very well.

For many of my repositories, I have configured GitHub's Dependabot to keep my workflows up-to-date with something like this in .github/dependabot.yml (similar to what this repository has as well):

version: 2
updates:
  - package-ecosystem: "github-actions"
    directory: "/"
    schedule:
      interval: "daily"
    assignees:
      - "mbg"

I note that a few hours ago, a v2.0 tag was pushed, which triggered Dependabot to open PRs to update the haskell/setup action on my repositories. Unfortunately, there are no proper release notes or a changelog, so it defaults to just showing the commits:

I wouldn't necessarily mind just having a list of commits, if the descriptions were more meaningful. However, as it stands, it's very difficult to judge whether I want to upgrade without reviewing the commits myself. Furthermore, seeing commit messages like the ones above might give people the wrong impression of what seems to generally be a fairly high quality action and is part of the haskell organisation.

Would it be possible to use more meaningful commit messages and/or publish release notes alongside new releases?

[hazelweakly]

Hey there, thanks for letting me know about that. There are a few things happening here, I think

• I try not to rebase and squash other people's commits in a git repo because I don't want to remove their contributions (it's "just" a UI thing in github, but I don't want to make work invisible); I also don't think that gatekeeping PRs on commit messages is helpful or productive. Particularly when, half the time, you have to use commit-driven-development to test GH Action pipelines 😅
• Pushing tags doesn't give me a chance to actually make a release to anything, and releases seem to be completely separate from tags
• I personally wasn't aware that this was dependabot's default behavior (whoops)

That said, I do think migrating to version 2 is a good idea. It switches to using node 16 which will become the default eventually for github actions. But I was planning on communicating that better (I've been strapped for time lately).

I'm not sure if I can change dependabot's message after the PR has already been opened by adding release notes, but this is definitely motivation for me to adopt something like changesets which should help make sure that there are "real" changelogs for everything in place. I appreciate you bringing it to my attention!

---

tl;dr

Would it be possible to use more meaningful commit messages and/or publish release notes alongside new releases?

Absolutely!

[sondr3]

Otherwise, if you include a changelog in the package root or write release notes for the tag in the Release-tab in the repo it will also be included as part of the PR from dependabot. You can see an example here. In general I would do both regardless, its already hard to know if updated actions require manual intervention when they are bumped. :slightly_smiling_face:

[mbg]

Thanks for the detailed response and explanation for what's new in version 2, @jared-w! I totally agree that gatekeeping PRs over commit messages wouldn't be great. As @sondr3 suggests, the easiest solution here is to probably just include a changelog in the root of the repository and then make sure that is up-to-date before you tag a new version, since dependabot will source release notes from that. Some further thoughts:

• It might be helpful to include some contribution guidelines in the root of the repository as well. GitHub will display these to new contributors in the UI when they are about to open their first PR. That way, you can e.g. encourage a particular style of commit messages as well as other good practices for PRs.
• AFAIK the "Squash & Merge" option in the GitHub UI still attributes the resulting commit to the PR author(s). It also defaults the commit message to the title of the PR, so in this case it would have been "feat: update to node 16", which is already a lot better than the merge commit. So that's a good option when the commit history of a given PR doesn't matter.

[hazelweakly]

The squash & merge option has broken preserving contributing commits to PR authors (off and on). I believe it currently makes me the main contributor and fails to show the PR author in the UI on the front-page of the repo, but that might've been fixed again.

I'll add changelogs as part of some cleaning up that I do to actually properly automate releases and make sure that the contributing docs are moved from the various folders to where they'll be visible for people.

It's already hard to know if updated actions require manual intervention when they are bumped

My personal policy with actions is to never break backwards compatibility, even across major version updates. The actions are a convenience and are intended to never be a maintenance burden; if they make your life more difficult, I've failed.

The only reason we released v2 here was because the actions.yml now specifies node 16 and I don't believe github will fallback appropriately; the code is still node 12 compatible (and will remain so as long as is feasible). So, morally speaking, it's only a "breaking change" for self hosted runners that don't have node 16 installed (but those do exist).

In general I would do both regardless

That's the plan :)

[sondr3]

My personal policy with actions is to never break backwards compatibility, even across major version updates.

But I have no easy way of knowing that 😄 Most major version releases have not had breaking changes but a few have been, or have deprecated a flow I was using and it's not always easy reading commits and knowing if they will break your workflow. Doubly so if they are for release jobs that only run on tags and so on.

[andreasabel]

Squashing via the github interface does preserve authorship as far as I have experienced, and I think it is good policy to squash commits in a PR if individual commits are not meaningful units, e.g. do not build, do not work without future commits, do not have meaningful commit messages.

Good commit hygiene enables automatic changelogs by tag comparison (and also advanced features like git bisect). E.g., here is one: https://github.com/haskell/actions/compare/v2.0.3...v2.0.4

[andreasabel]

Fixed by #164: Proper github releases are now created automatically by a workflow acting on tags "vx.y.z".