zig

commit dc97d119e6ac1a5e5f06f7457adf2a42d84b780d (tree)
parent b1184cdeab04f459e21f1118fea070a8e2e7ef5c
Author: Motiejus Jakštys <motiejus@jakstys.lt>
Date:   Wed, 25 Feb 2026 08:26:57 +0000

update Sema porting instructions for unattended agent operation

Fix numbering, add cross-references, clarify cleanup/regression policy,
add termination condition and stuck-handling guidance.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Diffstat:
M
stage0/README.md
 | 
44
+++++++++++++++++++++++++++-----------------

1 file changed, 27 insertions(+), 17 deletions(-)
diff --git a/stage0/README.md b/stage0/README.md
@@ -11,15 +11,15 @@ The goal of stage0 is to be able to implement enough zig to be able to build
 1. Lexer: DONE, written by hand by yours truly in late 2024.
 2. Parser: DONE, written mostly by an LLM.
 3. AstGen: DONE, written fully by an LLM.
-3. Sema: in progress.
+4. Sema: in progress.
 
 # Sema porting approach
 
 Goal: make `corpus_test.zig` skip over less tests. Rules:
 
 1. We have extensive AIR comparator: we generate AIR from the upstream Zig
-   compiler and compare it byte-by-byte (`Exceptions` below) to the C
-   implementation.
+   compiler and compare it byte-by-byte (see [Exceptions](#exceptions)) to the
+   C implementation.
 2. Run Red/Green TDD. The first step of Red/Green TDD is expanding the test
    suite by bumping the `num_passing` in `stage0/stages.zig`.
 3. Once test fails, we need to port enough code mechanically from Zig to C to
@@ -29,14 +29,20 @@ Goal: make `corpus_test.zig` skip over less tests. Rules:
     - Data structures should be the same, C <-> Zig interop permitting. I.e.
       struct definitions in `stage0/sema.h` should be, language permitting, the
       same as in `src/Sema.zig`.
-4. Sometimes the changes to enable a single stage can be quite complex and
-can't be enabled in one go. Then we split it into smaller tractable problems,
-by adding tests to `sema_test.zig`.
+4. If the changes required to enable a single test case feel too complex to
+   tackle in one go (subjectively: too many new functions, unclear failures,
+   multiple unrelated features needed at once), split it into smaller tractable
+   problems by adding focused tests to `sema_test.zig`. Get those passing
+   first, then return to the corpus test.
 5. Once progress is made (e.g. more AIR matches between C and Zig), clean up
-and commit.
+   (see [Cleaning Up](#cleaning-up)) and commit.
+6. If you get stuck (e.g. a test won't pass after several attempts), decompose
+   the problem into smaller pieces as described in step 4. Do not give up or
+   take shortcuts — keep splitting until the pieces are small enough to solve.
 
-Once a new test case has been enabled and passes, we enable the _next_ test
-case by bumping `num_passing` and repeat the process.
+Once a new test case has been enabled and passes, enable the _next_ test case
+by bumping `num_passing` and repeat the process. Continue until all corpus
+tests pass.
 
 ## Exceptions
 
@@ -51,15 +57,19 @@ C and Zig AIR must match byte-by-byte except:
 
 ## Cleaning Up
 
-1. Disable/skip failing tests (most likely the one that was enabled before).
-2. Remove or comment out all printf statements.
-3. Run `Quick test` (from below), ensure it passes and there is no extraneous
-   output.3. Run `More elaborate` test function (below) , ensure it passes and there is
-   no extraneous output.
+Before committing, ensure master stays green:
 
-If a test fails, perhaps it's a regression? We don't want to commit _less_ than
-we started with. Go back and analyze. If it's not a regression, you did a poor
-job in 1. If it's not a test failure, but a formatting/linting issue, fix it.
+1. Revert `num_passing` back so that only tests that actually pass are enabled.
+   If the test you just enabled still fails, lower `num_passing` to exclude it.
+2. Remove or comment out all printf statements.
+3. Run the quick test (`zig build fmt-zig0 test-zig0`, see [Testing](#testing)),
+   ensure it passes and there is no extraneous output.
+4. Run the more elaborate test (`zig build all-zig0 -Doptimize=ReleaseSafe`,
+   see [Testing](#testing)), ensure it passes and there is no extraneous output.
+
+If a test that previously passed now fails, that is a regression. Do not commit.
+Go back and fix it — we never commit with fewer passing tests than before. If
+it's not a test failure but a formatting/linting issue, fix it before committing.
 
 # Testing