I am looking for advice on how best to navigate Zig updates. There have been several cases where I fix a library that is not compiling due to Zig changes, just for Zig to change yet again and break the library. For example, zig recently moved std.io.File to std.fs.File. Easy enough, and two days ago I applied this fix to a TUI library. However if you test this with the master branch, rather than the latest release, we see that File has been entirely deprecated and no longer compiles.
Is this just a one off rarity or something that constantly troubles libraries written in Zig? I am fairly new to the language, but really enjoying it. I just don’t want another angular problem where documentation no longer reflects the accurate state of the language. I understand we are not yet 1.0 and to expect breaking changes, was just hoping for more clarity on the rate of these breaking changes, and the attitude of developers creating Zig on when it is appropriate to allow these kind of breaking changes, and when it is best to work around them ensuring continued support.
As a side note, any books that focus more on best practices so that the data within the book is no longer out of date would be great!
I guess it does happen to some frequency. If you just want stability through, my advice is to depend on a fixed version of the library that is compatible with the lastest release, like 0.15.2
In my case, some libraries I use have do have a local copy as a dependency, just to ensure that i can change it manually in case I download any recent version of zig that introduces some breaking changes. Since not every maintainer is expected to keep it up to date with the lastest version.
1 Like
When it comes to libraries I’d suggest to always go with tagged Zig releases, instead of using Zig master. And I’d also suggest to find libraries that are actively maintained and have a maintainer that has a track record of regularly updating to new Zig versions, there are some libraries out there that just got abandoned on an older version and you probably don’t want to maintain them yourself.
As for the amount of changes recently, it has definitely been more than usual. With the new IO interface many changes in the standard library are needed, and additionally they are taking this as an opportunity to rethink these parts of the standard library.
But in the past the level of change was quite low, usually I had to only change a couple dozen lines per update.
So I’d say you can expect maybe a few more releases with many breaking changes from the Io interface before it returns to normal levels.
There are a few cases where things are deprecated a release earlier, but note that Zig doesn’t have warnings, so there often is no way of knowing, unless you read the release notes.
For the most part though they will break things without a way to keep using the old version. However there is always migration help in the release notes, and it’s generally fairly easy to do the migration.
Furthermore most changes make things better, and I think it’s fine to have a little friction to get a better API, for example as part of the Io rewrite the entire time handling was improved to use more readable wrapper data structures to handle timestamps and durations. I had to change ~400 lines (out of over 40k) and in the end I think it improved not just the standard library, but my code as well.
And if you are unhappy with something, then you can also just copy it into your own project. The nice thing about Zig is that the standard library code is easy to read and navigate, so you can easily make it your own.
7 Likes
The context around rethinking the io parts of the std library is good to know. I appreciate you taking the time to inform me. Do you gather this context just watching the repository? Or is there some mailing list I can join to be as informed as you are? 
Most of it is just regularly checking the repository for new issues and PRs and then I subscribe to the ones that interest me to get a mail when they land.
But there are also often small discussions here on Ziggit when people get excited about a new feature that just got merged (an example for that: Juicy main is awesome :)), so I think you are already in the right place.
4 Likes
Yeah this is currently a very breaking period currently, and I think this will settle down a bit more after 0.16 is released, and become more stable again with 0.16.1 or following releases, they are in the process of implementing the Io interface, and out of all the things, I think Io is really hard to do, really hard to get right, and since it’s something all programs do, very breaking, it’s not unusual for Zig, I’ve been writing Zig since 0.10/0.11 and honestly it’s usually not that bad, with an easy path forward, but like anything it’s not for the weak and that’s why this community is great, if you don’t follow actively everything happening in Zig you can always come here and ask questions if you need some help understanding something or finding how to do X or Y in the new version of the language. But as @IntegratedQuantum said, it’s usually always worth to upgrade as there’s always a bunch of really useful improvements, that always improve the correctness, performance or clarity of the code. And the std is very easy to read, so much so that you can usually just learn the language by reading the std, the implementation and figure out how to use any api, by looking at usage in the test.
2 Likes