0.15.1 release notes do not cover all breaking changes. Why not enforce Conventional Commits so users could at least be able to find breaking changes on their own?
1 Like
What are Conventional Commits?
Do you mean this?: Conventional Commits
1 Like
precisely this
Marking breaking changes per commit may be useful, but note that Zig is intentionally and explicitly pre-1.0 and, by SemVerâs definition:
Major version zero (0.y.z) is for initial development. Anything MAY change at any time. The public API SHOULD NOT be considered stable.
4 Likes
We have such strict commit rules at work in some projects (enforced by a commit hook) and IMHO this is one little puzzle piece that starts to suck the fun out of coding. A couple of similar restrictions in other places and you create a bureaucratic monster.
PS: apparently the advantage is that you can automatically create a changelog from the git commit history, but this just results in spammy write-only changelogs that nobody will ever read (and why even maintain a changelog thatâs just a copy of the commit history).
15 Likes
This is to compensate poor release notes and docs.
1 Like
Writing meaningful commits should not be fun, you write them for others. Tho you still can have some fun if you apply some imagination. When properly used, changelog is not a copy of the commit history. Fun, this somewhat spoiled argument reminds me of the cali drivers (******* ********) attitude. Sure, it is boring to commit a full stop at a stop sign, but you are not alone on the road, so maybe fun stuff should not always be a priority, no? Especially in OSS, where most people do âseriousâ work so then they can have actual fun enjoying the results.
2 Likes
That is easy to say when you arenât the one that needs to write those commits.
It is always easier to create additional work for others, but when you are on the receiving end of those kind of management decisions, it can lead to burnout and loss of passion for the project.
Especially because once you go down that route, there is always one more additional way you âshouldâ be doing things.
I think a lot of times these kinds of ideas come from people who are still in the habit of chasing silver bullets, they donât exist, everything is a tradeoff and nothing achieves magic for free.
It is good to consider different solutions, but personally I donât see huge value in this convention, I speak only for myself here, but at most I would let people opt-in to creating commits using this format, nothing requiring it.
I would rather have the code, than fancy commit histories.
I am also somewhat sceptical of such things, for example the info about breaking changes already exists within the issue tracker, if you really want that info then you could create a tool that extracts that info by analyzing the commits and their associated issues.
If it isnât important enough to you to actually try to create such a tool, then my question would be: why should this be so important to everyone else then?
I think if there is a chance you could get similar information from the existing information within github, then you should explore that, instead of requiring additional work from everybody who is contributing.
15 Likes
Zig already tags breaking PRs with the breaking label for this purpose. This is in my opinion a lot more user friendly than a commit message convention.
And by the way, I assume you are mainly concerned about `stringify()` is gone. The PR that changed this, update std.json and std.zon to new I/O API by andrewrk ¡ Pull Request #24505 ¡ ziglang/zig ¡ GitHub, was labelled with a âbreakingâ label on github.
The release notes are already quite good in my opinion.
The fundamental problem is that humans make mistakes, and I donât see how a commit convention would help here given that there already is an established convention with the breaking label.
15 Likes
Iâve been writing CC commits for years (not just for my personal projects, but for every contribution to other projects (where it is not forbidden (but I never saw such rule yet)), so I know the exact amount of work it adds and the countless amount of work it removes. The reason I suggested this is that there is already some kind of format for commits. So its kinda wasteful not to utilize a more functional format if it does not add any work for writers (still have to format commits, just in a âdifferentâ way). Since nobody just writes âcNâ in commit messages (that would be discarded regardless of the code quality), there is no additional work (maybe a fear of change, but this is a different topic).
std.os.linux: delete restore and restore_rt for hexagon, loongarch,
fix(std.os.linux)!: delete restore and restore_rt for hexagon, loongarch,
The difference is pretty much nonexistent. Positive side effects are technically countless. This one is not a silver bullet, it is literally free work done by raccoons of silicon.
I could understand if everybody would have 0.04 WPM speed and every single character counts, but I am pretty sure this is not the case.
This improves current work, not âadds more workâ. Actually, the receiving side is the one that needs to put work to digest these commits (if needed).
Pulling this from GH was my initial idea, but it failed: GH issues are useless on this one because not all PRs have a tag reference (update std.json and std.zon to new I/O API by andrewrk ¡ Pull Request #24505 ¡ ziglang/zig ¡ GitHub).
2 Likes
Yea I saw this one, but there is no version reference. So if there is 0.16 release with json changes, there would be no way to precisely track the change in question (I donât remember any GH filters that could assist in such case).
1 Like
In that case just use git itself:
git tag --list --contains a288266f3310e9ba98456c5e968f8ce434be6cc7 | cat
0.15.0
0.15.1
1 Like
Because of
0.15.0
0.15.1
And this is kinda my question too. Why not use git for release notes and breaking changes? Format is already enforced, it just needs an adjustment. âIf you want to do the job right, use the right toolâ.
For manual search, it should work. But it looks like you still need to pull commits, idk if this would work efficiently with the GH API (if there are many PRs with many commits, youâre gonna hit the rate limit veeeery quickly).
Somehow this change is viewed like writing 500+ line essays lol. In fact, itâs just the usage of proper wording when you take into account current commit messages. Again, there is already a commit message format, tho it has zero functionality. With proper CC, nobody needs to spend hours on release notes, or labeling PRs, or making sure release notes and labels do not have any missing elements. Literally free magic that gives you more time to write code instead of doing redundant bureaucracy. Not to mention all the wins for consumers.
1 Like
I think commit messages and PR descriptions are the low-level, too detailed basis for writing release notes. Release notes should be a hand-crafted text, made for human readers by a human writer. And then thereâs little point in a structured format for the commit messages.
6 Likes
This is why you do git commit -m "low-level text" -m "high-level text". Then you combine high-level text into a release note. Maybe it is not a popular opinion, but this is how it was done before GH existed. The point is to not do the same work twice. But again, this appears to be not very popular.
Good release notes are always handwritten. Commits are often in an unusual order, and contain things that you donât want to read in release notes (a very simple example is fixing a bug that wasnât present in the previous release, or fundamentally changing a new feature). So youâd still want to spend hours of time fixing all these small details if you want good release notes.
Nothing in this world is free. What you are suggesting is writing commit messages so that they include what goes into the release notes. Especially in an open source project I think this is going to introduce a lot of friction, as not only the code but also the associated release note entries have to be reviewed. I think it is more efficient for a single person to collect this information in one go at the end, instead of nitpicking commit message grammar mistakes everywhere.
And you will get a more consistent style of writing as well, which in my opinion also makes it more pleasant to read. I donât want to read a document written by 100 different people poorly cobbled together by some algorithm.
6 Likes
I am not suggesting any auto-generated text. Commits are always in chronological order, would not work any other way. Of course one would want to get thro the note, and I am not saying that a summary is a nono. Tho the coolest thing is that all of this could be automated too, CC does not mean that every single commit goes into the release note (we are interested in breaking changes only on this one). Again, this is not about release notes; this is about the ability to trace breaking changes. To be precise, this is only about adjusting the current commit format. Release notes and etc are just a bonus. And it costs one word and a pair of parentheses (which is pretty much free for a human).
1 Like