Exactly the problem. People will sometimes split work into multiple PRs, now if someone else does some other change in the same category in between, then the chronological order is undesirable.
Except Zig does not have a commit format. If you scroll through the commit history you will see that there is no consistent format that is followed.
In either case, âConventional Commitsâ is not a relevant standard to appeal to. Tagging commits to Zig master as âbreaking changesâ would in fact violate the CC semantics:
Commits with
BREAKING CHANGEin the commits, regardless of type, should be translated toMAJORreleases.
Zig doesnât have major releases! It also doesnât have a release cadence or pre-release feature freezes, so when writing a commit message you donât know the baseline.
Like if I make a commit that changes the name of Andrewâs new std.mem.cutLast function to, uh, std.mem.snipRightmost, that may or may not be a breaking change, retroactively, depending on whether my commit makes it into the next release.
Maybe Iâm off base here but I think the reason Zig doesnât mandate this is more or less just the same as why Conventional Commits and Semantic Versioning donât mandate it or even specify its meaning for 0.x projects: because it imposes coordination costs and adds friction.
Zig intentionally remains at this SemVer phase:
Major version zero (0.y.z) is for initial development. Anything MAY change at any time. The public API SHOULD NOT be considered stable.
And it encourages the opposite of this:
Incompatible changes should not be introduced lightly to software that has a lot of dependent code. The cost that must be incurred to upgrade can be significant. Having to bump major versions to release incompatible changes means youâll think through the impact of your changes, and evaluate the cost/benefit ratio involved.
My vote is for the Zig team to do whatever makes them the most productive and happy, and to not distract them with commit formatting ideas if they arenât interested in changing right now.
I think we have hit the XY Problem. The problem is not the lack of CC. The problem is that you want a way to know when API X was changed so you can easily update. CC will not solve this problem.
So I guess a more productive discussion would be: what would you find actually helpful? Diffing an API across minor versions? API upgrade notes for every api change in a fast moving codebase with lots of different contributers?
Either way, I donât see adopting CC as actually fixing your problem. So letâs try shifting to the actual problem, not the proposed solution.
You can adjust the order during the formatting (I use PR numbers and email/author for this, but one could get away with regex or something else).
If this is not a format, then at least it looks like some attempts to keep things organized. Of course, if everybody wants to punk rock the thing, I donât really care how things are done (not my table really). I just feel like there is room to improve the issue with release notes, so I suggested an improvement since I donât have a habit of closing my eyes on things that require attention. What happens after is absolutely not my business.
Yes, CC is just the simplest way to track breaking changes efficiently since release notes are not very reliable. And it comes with tons of bonuses at the expense of organized commit history via 3-10 extra characters (some might argue that this is not an expense, but this is a metal show, not a jazz club, so I will call it an expense lol).
And it worked for me flawlessly for years. But I do know that my standards are too high for most since I do not like to waste my time. I havenât seen a better way to solve this, but I am down to write something new if you have better ideas (GH rate limits are breaking all my current drafts).
If I had to describe the problem, I think it would be this:
We need a way to see how Feature X from version 0.14 changed between 0.14 and 0.15. Ideally this needs to contain an upgrade plan as well.
Not all changes are made in small pieces. For example a commit to update all of std.json to use the new Io interfaces. This touches a lot of code and makes it challenging to write an update guide. Adds a lot of extra work for code that may be changed in the future anyway.
So instead of trusting the commit messages, we have to trace the changes forward. Given a starting commit and a file, we track to the first change, see if it impacted us, perhaps pick a new file to track to handle refactors, and repeat until you are at the destination commit. This is more manual, but there are parts that can be automated to make it more friendly.
Each pr that changes public api has to have an update guide. You can get all the prs for the last release cycle. You can then find the ones that touch the API you are concerned about and find upgrade guides.
This adds a lot of burden on the maintainers and contributers and potentially discourages people from helping out.
Croud source the upgrade guide through a forum like Ziggit. People help each other navigate all the crazy changes and provide nice solutions. This adds a delay as new issues have to be surfaced after the fact, but it seems to be working out nicely. Maintainers and contributers do their thing, and the community can support itself.
There may be other solutions, but ultimately it puts the work on someone. There are ways to inforce it, but it has a cost. It would be nice to automate it, possibly with LLMs as an option. Using the actual changes would be great since the code doesnât lie.
I doubt we will have a strong enough LLM before zig 5.0 to use with this topic. Maybe git blame. Gotta research this one, thanks!
Asking on the forum works, but I feel like I am wasting somebody elseâs time since there are tools already that would eliminate the need for a question in the first place.
Is there a way to automatically generate the breaking changes? Like running the feature tests from the previous version against the current version and see what have been broken. Ask a LLM to summarize it if you want to get fancy.
Some commits are not known at the times whether theyâre breaking or not. It might take a number of commits to cumulate into a breaking change.
That would require a dedicated instance that would need constant training on each version. Doable, but I doubt itâs going to happen since even the very basic and critical stuff like hash upgrade infra (package hashes) is considered a taboo for some reason (never saw a project blocking such work all the way to outside contributions). Not to mention LLM tracking breaking changes))). All LLM services are too moronic and unreliable to use with this issue, so you have to train your own.
Sometimes the author of a commit doesnât know that the commit is a breaking change.
I recently had such a case in another open source project. Another tiny change a few days later solved this then.
Semantic versioning is a success story, and when I first heard of it, its advantages were immediately clear to me, so I advocated it for our closed source project at work.
Whereas this discussion was the first time I heard of conventional commits and my first thought was âplease notâ. Probably the majority of developers felt similar, which explains why CC is not as successful.
But maybe if in a few years, CC is as common as semver, then Iâll be used to it from other projects and change my mind.
I realized last night that there is already a âreverse git blameâ. Git bisect will let you run forward the commits from 1 commit to another running a script at each commit. One could build tooling on top of this for tracing how a file/api changed. Another idea to throw in the mix.
Iâm half with you on this one. I think any amount of enforced rules on top of your coding will suck the joy out of it.
However, Iâve started to voluntarily do conventional commits everywhere, for my own sake. They donât feel as bad, thereâs a good amount of value added (mostly for myself, when git blaming my stupid mistakes from the past).
I canât make anyone like them and as such I wonât ever force anything thatâd make coding less fun, but I hope my testimony encourages you to try them with a different attitude, so theyâll eventually suck less for you.