ci: define and enforce the Zig toolchain policy

.github/workflows/ci.ymlmodified+51-6

Changes to .github/workflows/ci.yml

		⋯4 linesShow the 4 lines above this hunk@@ -5,25 +5,31 @@ on:
5	5	branches: [main, develop]
6	6	pull_request:
7	7	branches: [main, develop]
	8	+ schedule:
	9	+ - cron: '17 6 * * 1'
	10	+ workflow_dispatch:
8	11
9	12	jobs:
10	13	test:
11		- name: Test on ${{ matrix.os }} with Zig ${{ matrix.zig-version }}
	14	+ name: Test on ${{ matrix.os }} with supported Zig
12	15	runs-on: ${{ matrix.os }}
13	16	strategy:
14	17	matrix:
15	18	os: [ubuntu-latest, macos-latest]
16		- zig-version: ['0.17.0-dev']
17	19	fail-fast: false
18	20
19	21	steps:
20	22	- name: Checkout code
21	23	uses: actions/checkout@v6
22	24
	25	+ - name: Read supported Zig version
	26	+ id: zig-version
	27	+ run: echo "version=$(cat .zig-version)" >> "$GITHUB_OUTPUT"
	28	+
23	29	- name: Setup Zig
24	30	uses: pantry-pm/pantry/packages/action@main
25	31	with:
26		- packages: zig@0.17.0-dev
	32	+ packages: zig@${{ steps.zig-version.outputs.version }}
27	33
28	34	- name: Verify Zig installation
29	35	run: zig version
		⋯15 linesShow the 15 lines above this hunk@@ -45,10 +51,14 @@ jobs:
45	51	- name: Checkout code
46	52	uses: actions/checkout@v6
47	53
	54	+ - name: Read supported Zig version
	55	+ id: zig-version
	56	+ run: echo "version=$(cat .zig-version)" >> "$GITHUB_OUTPUT"
	57	+
48	58	- name: Setup Zig
49	59	uses: pantry-pm/pantry/packages/action@main
50	60	with:
51		- packages: zig@0.17.0-dev
	61	+ packages: zig@${{ steps.zig-version.outputs.version }}
52	62
53	63	- name: Check formatting
54	64	run: zig fmt --check .
		⋯6 linesShow the 6 lines above this hunk@@ -61,10 +71,14 @@ jobs:
61	71	- name: Checkout code
62	72	uses: actions/checkout@v6
63	73
	74	+ - name: Read supported Zig version
	75	+ id: zig-version
	76	+ run: echo "version=$(cat .zig-version)" >> "$GITHUB_OUTPUT"
	77	+
64	78	- name: Setup Zig
65	79	uses: pantry-pm/pantry/packages/action@main
66	80	with:
67		- packages: zig@0.17.0-dev
	81	+ packages: zig@${{ steps.zig-version.outputs.version }}
68	82
69	83	- name: Generate docs
70	84	run: zig build-lib -femit-docs src/lib.zig
		⋯12 linesShow the 12 lines above this hunk@@ -83,10 +97,14 @@ jobs:
83	97	- name: Checkout code
84	98	uses: actions/checkout@v6
85	99
	100	+ - name: Read supported Zig version
	101	+ id: zig-version
	102	+ run: echo "version=$(cat .zig-version)" >> "$GITHUB_OUTPUT"
	103	+
86	104	- name: Setup Zig
87	105	uses: pantry-pm/pantry/packages/action@main
88	106	with:
89		- packages: zig@0.17.0-dev
	107	+ packages: zig@${{ steps.zig-version.outputs.version }}
90	108
91	109	- name: Install kcov
92	110	continue-on-error: true
		⋯28 linesShow the 28 lines above this hunk@@ -121,3 +139,30 @@ jobs:
121	139	- name: Coverage skipped
122	140	if: steps.install-kcov.outcome != 'success'
123	141	run: echo "kcov not available on this platform, skipping coverage"
	142	+
	143	+ latest-zig:
	144	+ name: Compatibility with latest Zig 0.17.0-dev
	145	+ if: github.event_name == 'schedule' || github.event_name == 'workflow_dispatch'
	146	+ continue-on-error: true
	147	+ runs-on: ubuntu-latest
	148	+
	149	+ steps:
	150	+ - name: Checkout code
	151	+ uses: actions/checkout@v6
	152	+
	153	+ - name: Setup latest Zig development build
	154	+ uses: pantry-pm/pantry/packages/action@main
	155	+ with:
	156	+ packages: zig@0.17.0-dev
	157	+
	158	+ - name: Verify Zig installation
	159	+ run: zig version
	160	+
	161	+ - name: Build framework
	162	+ run: zig build
	163	+
	164	+ - name: Run tests
	165	+ run: zig build test
	166	+
	167	+ - name: Run examples
	168	+ run: zig build examples

.zig-versionadded+1-0

Changes to .zig-version

		@@ -0,0 +1,1 @@
	1	+0.17.0-dev.2163+89ff10d56

CONTRIBUTING.mdmodified+1-1

Changes to CONTRIBUTING.md

		⋯25 linesShow the 25 lines above this hunk@@ -26,7 +26,7 @@ Thank you for your interest in contributing to the Zig Test Framework! This docu
26	26
27	27	### Prerequisites
28	28
29		-- Zig 0.15.1 or later
	29	+- The exact Zig development build recorded in [`.zig-version`](.zig-version)
30	30	- Git
31	31	- Basic understanding of testing frameworks (Jest, Vitest, or similar)
32	32

README.mdmodified+4-1

Changes to README.md

		⋯755 linesShow the 755 lines above this hunk@@ -756,7 +756,10 @@ zig build examples
756	756
757	757	## Requirements
758	758
759		-- Zig 0.15.1 or later
	759	+- The exact Zig development build recorded in [`.zig-version`](.zig-version)
	760	+
	761	+See [TOOLCHAIN.md](TOOLCHAIN.md) for the compatibility policy and upgrade
	762	+process.
760	763
761	764	## Documentation
762	765

TOOLCHAIN.mdadded+23-0

Changes to TOOLCHAIN.md

		@@ -0,0 +1,23 @@
	1	+# Zig toolchain policy
	2	+
	3	+The Zig Test Framework supports the exact Zig development build recorded in
	4	+`.zig-version`. Required CI jobs use that version so pull requests are tested
	5	+against a reproducible toolchain.
	6	+
	7	+Because the project follows Zig development builds, CI also runs a scheduled
	8	+compatibility check against the latest `0.17.0-dev` build. That check is
	9	+informational: an upstream API change should produce an intentional toolchain
	10	+update rather than unexpectedly blocking unrelated pull requests.
	11	+
	12	+## Updating Zig
	13	+
	14	+1. Replace the version in `.zig-version` with the full output of `zig version`.
	15	+2. Run `zig fmt --check .`.
	16	+3. Run `zig build`, `zig build test`, and `zig build examples`.
	17	+4. Run `zig build-lib -femit-docs src/lib.zig` and remove the generated local
	18	+ artifacts after verifying the command succeeds.
	19	+5. Summarize required compatibility changes in the pull request and, for a
	20	+ release, in the changelog.
	21	+
	22	+The compatibility job can also be run manually from GitHub Actions before
	23	+updating the pinned version.

build.zigmodified+1-3

Changes to build.zig

		⋯26 linesShow the 26 lines above this hunk@@ -27,9 +27,7 @@ pub fn build(b: *std.Build) void {
27	27	const run_cmd = b.addRunArtifact(exe);
28	28	run_cmd.step.dependOn(b.getInstallStep());
29	29
30		- if (b.args) |args| {
31		- run_cmd.addArgs(args);
32		- }
	30	+ run_cmd.addPassthruArgs();
33	31
34	32	const run_step = b.step("run", "Run the test framework");
35	33	run_step.dependOn(&run_cmd.step);

build.zig.zonmodified+2-0

Changes to build.zig.zon

		⋯4 linesShow the 4 lines above this hunk@@ -5,9 +5,11 @@
5	5	.paths = .{
6	6	"build.zig",
7	7	"build.zig.zon",
	8	+ ".zig-version",
8	9	"src",
9	10	"tests",
10	11	"examples",
	12	+ "TOOLCHAIN.md",
11	13	"README.md",
12	14	"LICENSE",
13	15	},

src/compat.zigmodified+6-6

Changes to src/compat.zig

		⋯112 linesShow the 112 lines above this hunk@@ -113,7 +113,7 @@ fn closeFd(fd: std.posix.fd_t) void {
113	113	/// Read entire file contents using POSIX APIs.
114	114	/// Replaces std.fs.cwd().openFile() + file.readToEndAlloc().
115	115	pub fn readFileAlloc(allocator: std.mem.Allocator, path: []const u8) ![]const u8 {
116		- const path_z = try allocator.dupeZ(u8, path);
	116	+ const path_z = try allocator.dupeSentinel(u8, path, 0);
117	117	defer allocator.free(path_z);
118	118
119	119	const fd = std.posix.openatZ(std.posix.AT.FDCWD, path_z, .{}, 0) catch |err| {
		⋯19 linesShow the 19 lines above this hunk@@ -139,7 +139,7 @@ pub fn readFileAlloc(allocator: std.mem.Allocator, path: []const u8) ![]const u8
139	139	/// Write content to a file using POSIX APIs.
140	140	/// Replaces std.fs.cwd().createFile() + file.writeAll().
141	141	pub fn writeFile(allocator: std.mem.Allocator, path: []const u8, content: []const u8) !void {
142		- const path_z = try allocator.dupeZ(u8, path);
	142	+ const path_z = try allocator.dupeSentinel(u8, path, 0);
143	143	defer allocator.free(path_z);
144	144
145	145	const fd = std.posix.openatZ(std.posix.AT.FDCWD, path_z, .{
		⋯15 linesShow the 15 lines above this hunk@@ -161,7 +161,7 @@ pub fn writeFile(allocator: std.mem.Allocator, path: []const u8, content: []cons
161	161	/// Delete a file using POSIX APIs.
162	162	/// Replaces std.fs.cwd().deleteFile().
163	163	pub fn deleteFile(allocator: std.mem.Allocator, path: []const u8) !void {
164		- const path_z = try allocator.dupeZ(u8, path);
	164	+ const path_z = try allocator.dupeSentinel(u8, path, 0);
165	165	defer allocator.free(path_z);
166	166	const rc = std.c.unlink(path_z);
167	167	if (rc != 0) {
		⋯7 linesShow the 7 lines above this hunk@@ -175,7 +175,7 @@ pub fn deleteFile(allocator: std.mem.Allocator, path: []const u8) !void {
175	175	/// Create directories recursively using POSIX APIs.
176	176	/// Replaces std.fs.cwd().makePath().
177	177	pub fn makePath(allocator: std.mem.Allocator, path: []const u8) !void {
178		- const path_z = try allocator.dupeZ(u8, path);
	178	+ const path_z = try allocator.dupeSentinel(u8, path, 0);
179	179	defer allocator.free(path_z);
180	180
181	181	const rc = std.c.mkdir(path_z, 0o755);
		⋯7 linesShow the 7 lines above this hunk@@ -189,7 +189,7 @@ pub fn makePath(allocator: std.mem.Allocator, path: []const u8) !void {
189	189	if (sep > 0) {
190	190	try makePath(allocator, path[0..sep]);
191	191	// Retry creating the directory
192		- const retry_z = try allocator.dupeZ(u8, path);
	192	+ const retry_z = try allocator.dupeSentinel(u8, path, 0);
193	193	defer allocator.free(retry_z);
194	194	const rc2 = std.c.mkdir(retry_z, 0o755);
195	195	if (rc2 != 0 and std.c.errno(rc2) != .EXIST) {
		⋯102 linesShow the 102 lines above this hunk@@ -298,7 +298,7 @@ pub fn spawnAndWait(
298	298	defer allocator.free(c_argv);
299	299
300	300	for (argv, 0..) |arg, i| {
301		- const z = try allocator.dupeZ(u8, arg);
	301	+ const z = try allocator.dupeSentinel(u8, arg, 0);
302	302	c_argv[i] = z.ptr;
303	303	}
304	304	c_argv[argv.len] = null;

src/snapshot.zigmodified+8-8

Changes to src/snapshot.zig

		⋯250 linesShow the 250 lines above this hunk@@ -251,16 +251,16 @@ pub const Snapshot = struct {
251	251	},
252	252	.@"struct" => {
253	253	try writer.writeAll("{\n");
254		- inline for (type_info.@"struct".fields, 0..) |field, i| {
	254	+ inline for (type_info.@"struct".field_names, 0..) |field_name, i| {
255	255	if (self.options.pretty_print) {
256	256	try writer.writeAll(" ");
257	257	}
258		- try writer.print("\"{s}\": ", .{field.name});
	258	+ try writer.print("\"{s}\": ", .{field_name});
259	259
260		- const field_value = @field(value, field.name);
	260	+ const field_value = @field(value, field_name);
261	261	try self.formatJsonValue(writer, field_value);
262	262
263		- if (i < type_info.@"struct".fields.len - 1) {
	263	+ if (i < type_info.@"struct".field_names.len - 1) {
264	264	try writer.writeAll(",");
265	265	}
266	266	if (self.options.pretty_print) {
		⋯40 linesShow the 40 lines above this hunk@@ -307,10 +307,10 @@ pub const Snapshot = struct {
307	307
308	308	try writer.writeAll("{\n");
309	309
310		- inline for (type_info.@"struct".fields, 0..) |field, i| {
311		- try writer.print(" \"{s}\": ", .{field.name});
	310	+ inline for (type_info.@"struct".field_names, 0..) |field_name, i| {
	311	+ try writer.print(" \"{s}\": ", .{field_name});
312	312
313		- const field_value = @field(value, field.name);
	313	+ const field_value = @field(value, field_name);
314	314	const FieldType = @TypeOf(field_value);
315	315	const field_info = @typeInfo(FieldType);
316	316
		⋯11 linesShow the 11 lines above this hunk@@ -328,7 +328,7 @@ pub const Snapshot = struct {
328	328	else => try writer.print("{any}", .{field_value}),
329	329	}
330	330
331		- if (i < type_info.@"struct".fields.len - 1) {
	331	+ if (i < type_info.@"struct".field_names.len - 1) {
332	332	try writer.writeAll(",\n");
333	333	} else {
334	334	try writer.writeAll("\n");