|
|
@@ -0,0 +1,89 @@
|
|
|
+# Git branches and tags — how this repository is organised
|
|
|
+
|
|
|
+**Snapshot:** 2026-10-22, stop point. `master` = `c2664ac`, in sync
|
|
|
+with `origin/master`. 298 tags (mostly historical `v3-*` checkpoints).
|
|
|
+
|
|
|
+Mental model:
|
|
|
+
|
|
|
+> **Branches move; tags don't.** Only `master` is active. Tags are
|
|
|
+> labels on commits (checkpoints), not lines of development.
|
|
|
+
|
|
|
+## Branches
|
|
|
+
|
|
|
+| Branch | State | What it is |
|
|
|
+| --- | --- | --- |
|
|
|
+| **`master`** | `c2664ac`, in sync with `origin/master` | The only active branch; all current work is here. |
|
|
|
+| `ast-stage-c` | `0f611c0` (2026-10-08), local only | Old stage branch, fully merged into master. Stale. |
|
|
|
+| `generics-inc1` | `6639c19`, 6 commits behind `origin/generics-inc1` | Old generics work, fully merged into master. Stale. |
|
|
|
+| `resolve-check` | `95ca4d6`, in sync with origin | Old branch merged into master. Stale. |
|
|
|
+
|
|
|
+`git branch --merged master` lists all of them: **nothing is unmerged**.
|
|
|
+The old branches may be deleted locally with
|
|
|
+`git branch -d ast-stage-c generics-inc1 resolve-check` (optional and
|
|
|
+harmless).
|
|
|
+
|
|
|
+Remote branches: `origin/master`, `origin/generics-inc1`,
|
|
|
+`origin/resolve-check` (there is no `origin/ast-stage-c`).
|
|
|
+
|
|
|
+## Feature tags — the session's real history
|
|
|
+
|
|
|
+Each points at the commit that landed a feature, all with green gates:
|
|
|
+
|
|
|
+| Tag | Commit | Work |
|
|
|
+| --- | --- | --- |
|
|
|
+| `v3-corpus-triage` | `aa4f49b` | PIM multi-index arrays, typed subranges, ordinal `FOR` (+12) |
|
|
|
+| `v3-empty-string` | `f87bcc9` | ISO `""` as `CHAR` (+6) |
|
|
|
+| `v3-libc-prototypes` | `c02fd41` | typed libc prototypes, `printf` varargs (+6) |
|
|
|
+| `v3-system-types` | `713650f` | SYSTEM sized types + qualified `SYSTEM` (+8) |
|
|
|
+| `v3-proc-types` | `f236600` | ISO procedure-type syntax (+4) |
|
|
|
+| `v3-byte` | `7621f16` | true 8-bit `BYTE`/`SBYTE` |
|
|
|
+| `v3-word16` | `a5d0f16` | true 16-bit `WORD16`/`CARDINAL16`/`INTEGER16` |
|
|
|
+| `v3-sysclock` | `4d05afe` | ISO `SysClock` (+2) |
|
|
|
+| `v3-smallfix` | `87e8605` | small conformance items (+6) |
|
|
|
+
|
|
|
+These are immutable checkpoints. Useful commands:
|
|
|
+
|
|
|
+```sh
|
|
|
+git show --stat v3-smallfix
|
|
|
+git diff v3-sysclock v3-smallfix # what the last step changed
|
|
|
+```
|
|
|
+
|
|
|
+## Session tags — why there are three similar names
|
|
|
+
|
|
|
+| Tag | Points at | Meaning |
|
|
|
+| --- | --- | --- |
|
|
|
+| `v3-session-2026-10-19` | `c9c1121` | Previous session's final summary. |
|
|
|
+| `v3-session-2026-10-22` | `c2664ac` | **Moving** session tag. Advanced several times and force-pushed to the final commit. |
|
|
|
+| `v3-session-2026-10-22-final` | `0e81019` | **Early checkpoint** created before the session continued (byte/word16/SysClock/smallfix came after). Historical noise now. |
|
|
|
+| `v3-session-2026-10-22-end` | `c2664ac` | **Final immutable session tag.** Use this one. |
|
|
|
+
|
|
|
+For "where did the 2026-10-22 session end?":
|
|
|
+
|
|
|
+- **canonical:** `v3-session-2026-10-22-end` (or `master`, same commit);
|
|
|
+- `v3-session-2026-10-22` is equivalent now, but it is a *moving* tag
|
|
|
+ by convention — avoid moving tags in the future;
|
|
|
+- `v3-session-2026-10-22-final` is **not** the end; it is an earlier
|
|
|
+ checkpoint at `0e81019`.
|
|
|
+
|
|
|
+To remove the stale checkpoint (tag only, no commits/code):
|
|
|
+
|
|
|
+```sh
|
|
|
+git tag -d v3-session-2026-10-22-final
|
|
|
+git push origin :refs/tags/v3-session-2026-10-22-final
|
|
|
+```
|
|
|
+
|
|
|
+## Why 298 tags?
|
|
|
+
|
|
|
+The project convention is one `v3-*` tag per green step across all
|
|
|
+sessions (two-phase parse slices, generics increments, Unicode, stdlib,
|
|
|
+…). They are a searchable history of passing states, not branches.
|
|
|
+`git tag --list | wc -l` = 298 is expected; only the recent ones above
|
|
|
+matter for the current session.
|
|
|
+
|
|
|
+## Current state
|
|
|
+
|
|
|
+- `master` = `c2664ac`, **synced** with `origin/master`.
|
|
|
+- All feature tags and session tags are on the remote.
|
|
|
+- Nothing to push.
|
|
|
+- Next session: start from `master` and read
|
|
|
+ `docs/handoff-2026-10-22-next.md`.
|
