[internal] Improve Release Automation and Changelog

[pedro-psb]

I'm creating this discussion to help organize and plan how we can implement a better release automation and changelog generation.

Release

• Move the release process to GitHub Action
• Define a trigger for the release. E.g:
  1. On tag push: when a commit that contains a tag (we only use tags for tagging releases).
  2. Manual: manually triggering the action inside GitHub (maybe via gh cli).

This would make it very straightforward to do new releases.

Changelog and Conventional Commits

In addition, we could also improve the changelog generation by using some changelog generator tool.
I've taken a look in git-cliff and it looks good. It provides python bindings, GH Actions integrations and customizable templates. There is also github-changelog-generator.

In any case, all we'll have to do besides setting it up is adopting some commit name convention (based on conventional commits). This naming will only happen when merging PR to master, where we usually do a squash-merge.

---

Status

• on-merge-with-tag workflow publishes PyPi package, GitHub Release, and Netlify. This assumes the tagged commit is properly tagged, and has the updated version refs and updated changelog. (commit)
• on manual dispatch, create the release-commit described above and push it.
  • Properly parse inputs (release: patch | minor) + bump version refs
  • Generate changelog
    • Proper update the changelog based on versions provided
    • Customize the template (to be like the release generated by using the web interface)
    • Properly add the "@nameref" of the contributors.
  • Create tagged commit and push

[pedro-psb]

There is a PyPi action to publish releases, which seems to be able to trigger-on-tag out of the box.

Anyway, here are some usefull links regarding tag filtering:

• https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#example-including-branches-and-tags
• https://stackoverflow.com/questions/61891328/trigger-github-action-only-on-new-tags

on:
  push:
    # Pattern matched against refs/tags
    tags:        
      - '*'           # Push events to every tag not containing /
      - '**'           # Push events to every tag including hierarchical tags like v1.0/beta
      - 'v[0-9]+.[0-9]+.[0-9]+' # strictly vX.Y.Z

[pedro-psb]

For changelogs, I think it is also worth mentioning towncrier. It has a different approach than the previous idea of using git commits to generate changelogs. Instead, markdown "fragments" are placed inside a specific folder and should be "consumed" to generate the changelog on release.

The advantage is that this manual entry may be a little cleaner in general. For example, in the case of one PR that does two things, the commit-based changelog would produce one entry for the two, while here we would write two fragments and generate two entries afterward. In the end, it is an experience close to just writing directly to a changelog, but it provides some conveniences, like templates and the idea of fragments, which avoids merge conflicts. The downside is that we'll have to write the fragments rs

[pedro-psb]

Related: #547

[pedro-psb]

Closed by: #1072