search

NixOS / nixpkgs-check-by-name

Tool to check Nixpkgs' pkgs/by-name directory
MIT License
9 stars 3 forks source link

Version and changelog #38

Open infinisil opened 2 months ago

infinisil commented 2 months ago

We should have a changelog and decide the versioning scheme along with it. These are some thoughts regarding that, prompted via https://github.com/NixOS/nixpkgs-check-by-name/pull/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 commented 2 months ago

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 commented 2 months ago

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 :sweat_smile:. So instead I'd like to focus on tools that allow writing explicit user-focused changelog entries.

willbush commented 2 months ago

Just sprinkle some AI on it. /s

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

infinisil commented 2 months ago

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 commented 2 months ago

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: https://github.com/NixOS/nixpkgs-check-by-name/pull/48

willbush commented 1 week ago

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.