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

Version and changelog #38

Open
infinisil opened this issue Apr 9, 2024 · 7 comments
Open

Version and changelog #38

infinisil opened this issue Apr 9, 2024 · 7 comments

Comments

@infinisil
Copy link
Member

We should have a changelog and decide the versioning scheme along with it. These are some thoughts regarding that, prompted via #37.

I'm not considering changelog tools that use the Git log, because I don't think the Git log is valuable for users. I'd like to require each PR to submit such a changelog entry file (with an option to explicitly declare the PR as not changelog-worthy) (first seen here), and then using a tool to generate the changelog when it's time for a release:

Regarding versions, there's various versioning schemes, but I'm liking EffVer the most, and it matches the existing versions 0.1.0 and since recently 0.1.1.

I would like the automated weekly update PRs to also take care of bumping the release and changelog automatically if there's been any changes. To figure out the next version, all change entries should be tagged with the level of effort required to update (one of macro/meso/micro). Then the next version can be generated by increasing the previous one by that level. Though it's not perfect, because 100 micro changes could amount to a meso/macro change. So being able to adjust the automatically generated version number would be good too (also for an eventual 1.0.0 release).

Note that we should take some precaution to not miss PRs that might get merged during which the release/update PR is open, probably by making sure that a commit gets tagged instead of the merged commit.

@willbush
Copy link
Member

willbush commented Apr 9, 2024

Oh just got to this in my notifications. I just mentioned https://git-cliff.org/ in another PR. Just wanted to mention it. I don't have any strong opinions on the matter.

@infinisil
Copy link
Member Author

Yeah, as also mentioned above, I'm not a fan of generating release notes from git commits, since they're often very developer-focused instead of user-focused. E.g. like 80% of recent commits shouldn't even end up in the changelog 😅. So instead I'd like to focus on tools that allow writing explicit user-focused changelog entries.

@willbush
Copy link
Member

willbush commented Apr 9, 2024

Just sprinkle some AI on it. /s

I think you make a good point. I haven't looked through your list yet.

@infinisil
Copy link
Member Author

So I don't forget: We really need to switch away from the "merging to main triggers release" mechanism, because we can end up releasing things that weren't in the PR branch (from PR's that were merged to main in the mean time), without the respective changelogs.

A simple solution to this is to adjust the release action to target the second parent commit of the merge commit, which is the last commit in the release PR, which doesn't include the changes from main.

@infinisil
Copy link
Member Author

Thinking more about this, I don't think that would be a great solution (also it would be wrong, because the PR's head is never tested, the merge into base is tested). Instead the automated release PR should automatically rebase itself and regenerate the latest changelog, such that merging it will never not include a PR merged in the meantime.

Furthermore, to guarantee that we generally make sure to only release code that passed CI: #48

@willbush
Copy link
Member

https://news.ycombinator.com/item?id=40818781 found this interesting and this example changelog https://github.com/ratatui-org/ratatui/blob/main/CHANGELOG.md seems really good.

@infinisil
Copy link
Member Author

Might be worth checking out: https://lobste.rs/s/lsqbbf/effective_changelogs

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

No branches or pull requests

2 participants