The record of 2026-11-06, and issue and PR templates (#110)

FABRIC-3.md XLV, CHANGELOG, the issue forms and the PR template. Closes #108. Accepted by acceptance.yml, run 159, on 810d02eb.
2026-11-06 20:33:35 +00:00
parent c809de7393 810d02ebb3
commit 82804f2770
8 changed files with 332 additions and 0 deletions
@@ -0,0 +1,53 @@
 name: Bug
 about: Something is wrong. Report it as found -- it is fixed only when Captain Bob says so.
 title: "[bug] "
 labels: ["kind/bug"]
 body:
  - type: markdown
    attributes:
      value: |
        Write what was **found**, with its evidence. The rest of the issue follows the project's
        record (`docs/fabric/FABRIC-3.md`): **Ruled** (Captain Bob decides whether and how it is
        fixed), **Built** (the commits), **Verified** (the acceptance logs). A finding is not a
        request to fix it (`.claude/CLAUDE.md`, Hard Rules).
  - type: textarea
    id: found
    attributes:
      label: Found
      description: What is wrong, and what happens because of it. Concrete input and the wrong output, crash or hang.
    validations:
      required: true
  - type: input
    id: where
    attributes:
      label: Where
      description: File and line, or the word, capsule or board.
      placeholder: "v4/src/exec.c:182"
    validations:
      required: true
  - type: dropdown
    id: system
    attributes:
      label: System
      options: ["v4 (the default)", "v3 (system=v3)", "both", "the build or CI", "not specific"]
    validations:
      required: true
  - type: dropdown
    id: isa
    attributes:
      label: Seen on
      multiple: true
      options: ["amd64", "aarch64", "riscv64", "32-bit build (test-32)", "the PC stick", "hosted", "real hardware"]
  - type: textarea
    id: evidence
    attributes:
      label: Evidence
      description: The serial log (`logs/<TS>/<arch>/...`), the failing test, or the steps that reproduce it. Logs are the evidence; paste the lines that matter.
      render: text
    validations:
      required: true
  - type: textarea
    id: how
    attributes:
      label: How it was found
      description: A boot, a test, a review, real hardware.
@@ -0,0 +1,40 @@
 name: Work item
 about: A piece of planned work -- a step of a design, or something a ruling asked for.
 title: ""
 labels: ["kind/feature"]
 body:
  - type: textarea
    id: goal
    attributes:
      label: What
      description: The work, in a sentence or two.
    validations:
      required: true
  - type: textarea
    id: why
    attributes:
      label: Why -- the ruling or the design it comes from
      description: Captain Bob's ruling (quoted, with its date) or the document and section, e.g. `docs/v4.0.0/ENGINE.md` section 5, step 3.
    validations:
      required: true
  - type: textarea
    id: done
    attributes:
      label: Done when
      description: What will be true, and how it is shown. Every change to the kernel or v4 is accepted by the acceptance protocol -- the three ISA boots, the PC stick loaded high, test-32 -- with its logs committed.
      value: |
        - [ ] 
        - [ ] Acceptance passes, logs in `logs/`
    validations:
      required: true
  - type: dropdown
    id: area
    attributes:
      label: Area
      multiple: true
      options: ["kernel", "v4", "v3", "capsules", "proofs", "docs", "CI and build"]
  - type: dropdown
    id: priority
    attributes:
      label: Priority
      options: ["must -- needed for the milestone", "should -- needed for the product", "nice to have"]
@@ -0,0 +1,41 @@
 name: Ruling needed
 about: A decision only Captain Bob can make -- an open question, a trade-off, a design choice.
 title: "[ruling] "
 labels: ["status/blocked"]
 body:
  - type: markdown
    attributes:
      value: |
        Lay out the question so it can be ruled on. The ruling is recorded as it always is --
        **Ruled (Captain Bob, date)** -- in the document it belongs to, and the issue closed with a
        link to that record.
  - type: textarea
    id: question
    attributes:
      label: The question
    validations:
      required: true
  - type: textarea
    id: options
    attributes:
      label: The options, and what each costs
      description: Each choice with its consequences -- code size, speed, what it rules out later.
    validations:
      required: true
  - type: textarea
    id: recommendation
    attributes:
      label: Recommendation
      description: Which option, and why. A recommendation, not a decision.
  - type: input
    id: record
    attributes:
      label: Where the ruling will be recorded
      placeholder: "docs/v4.0.0/DECOMPOSITION.md section 3, D-4"
    validations:
      required: true
  - type: textarea
    id: waits
    attributes:
      label: What waits on it
      description: Issues or work that cannot go on until this is ruled.
@@ -0,0 +1,38 @@
 name: Board bring-up
 about: A board on real hardware -- a first boot, a failure, a step of boards/BRINGUP.md.
 title: "[board] "
 labels: ["kind/feature"]
 body:
  - type: dropdown
    id: board
    attributes:
      label: Board
      options: ["PC (SER5)", "Raspberry Pi 5", "Raspberry Pi 4 (not ported)", "Milk-V Mars", "Zynq-7020", "other"]
    validations:
      required: true
  - type: input
    id: image
    attributes:
      label: Image
      description: Which image was booted -- the nightly's Nexus version, or the commit it was built from.
      placeholder: "kernelImage-2.1.0-20261107.030000-1-raspi5.img.xz, or 0fd7648a"
    validations:
      required: true
  - type: textarea
    id: found
    attributes:
      label: What happened
      description: How far it got -- the last line seen on serial or screen.
    validations:
      required: true
  - type: textarea
    id: log
    attributes:
      label: Serial log
      description: The whole log if there is one; where it is committed (`logs/<TS>/...`).
      render: text
  - type: input
    id: bringup
    attributes:
      label: boards/BRINGUP.md item
      placeholder: "A1, S3, ..."
@@ -0,0 +1,6 @@
 # The issue picker. A blank issue is still allowed, for anything the forms do not fit.
 blank_issues_enabled: true
 contact_links:
  - name: Design, documentation and discussion -- the project wiki
    url: https://www.starshipos-f18.org/
    about: The XWiki is the project's entry point. Issues here are for work in this repository.
@@ -0,0 +1,20 @@
 ## What and why
 <!-- What this changes, and the ruling, issue or design section it carries out. -->
 Closes #
 ## Acceptance
 The **Acceptance** check runs on this pull request by itself -- amd64, aarch64, riscv64, the PC
 stick loaded high, test-32 -- and `master` takes nothing that has not passed it. Note here
 anything it does not cover:
 - [ ] Logs from runs made by hand are committed in `logs/`, if any
 - [ ] Hardware this was tried on, if any:
 ## The record
 - [ ] `docs/fabric/FABRIC-3.md` has the ruling and what was built, if this is design work
 - [ ] `CHANGELOG.md`, if it is a milestone
 - [ ] Nothing in this PR is a fix nobody asked for (`.claude/CLAUDE.md`, Hard Rules)
@@ -1,5 +1,20 @@
 # Changelog
 ## 2026-11-06 — One process from developer to master: the acceptance gate, the nightlies to Nexus, one repository
 Every pull request into `master` now runs the acceptance protocol (`acceptance.yml`): the three
 ISA boots, the PC stick loaded high, `test-32`, through the same `scripts/nightly.sh` stages a
 developer runs by hand. `master` is protected: no direct pushes, and nothing merges unless that
 check passed. The nightly (03:00 UTC) runs the same protocol plus the proofs and publishes the
 board images to Nexus as `org.starship:kernelImage:2.1.0-SNAPSHOT` (classifiers `pc`, `raspi5`,
 `milkv`, `logs`); the documents follow at 04:00 as `org.starship:documentation`; a `v<version>`
 tag publishes a release. CI jobs now run on Ubuntu 24.04 -- the runner's default was Debian 11,
 where every job had failed. `make ARCH=<arch> init` installs the whole toolchain, syft and
 Isabelle2025-2 included; the Doxygen API reference builds again. Three v4 bugs fixed (line input
 on both front ends; a refused store moving A or P). The StarForth repository's history is kept as
 the tag `archive/starforth-2026-09-17` and the repository deleted; this one is renamed
 `LithosAnanke`. Full record: `docs/fabric/FABRIC-3.md` XLV.
 ## 2026-10-09 — StarForth v4.0.0 Step 6e review and wire refinement
 Implemented whole-message handling on the engine wire (`d5cd6460`), ensured nodes only process one message at a time (`b1d09af0`), and refined message processing logic (`6a7d0aa2`, `f1419e73`). Fixed wake-up order, room checks, and overflow issues during message transit (`83694b18`).
@@ -5942,3 +5942,122 @@ and a 3 GiB boot added to acceptance.
 Not covered by QEMU: a load above 4 GiB (OVMF keeps images below it). The relocation check
 covers that case statically -- no 32-bit absolute is left to break there.
 ## XLV. One process from the developer to master: the acceptance gate, the nightlies, Nexus, and Gitea used as more than a repo (2026-11-06)
 **Ruled** (Captain Bob, 2026-11-06). What a developer runs by hand, what a pull request into
 `master` runs, and what the nightly runs are one process -- the acceptance protocol -- and
 "failures should not be allowed to be merged to master". Neither agile nor waterfall: the
 **Captain Bob method**. The images go to Nexus nightly as
 `org.starship:kernelImage:<LITHOS_VERSION>-SNAPSHOT`. The StarForth repository goes; LithosAnanke
 holds everything. Gitea is used for issues, milestones, a project board and pull requests -- not
 its wiki: the `.org` XWiki is the project's entry point, the `.com` its public face.
 ### 1. The review, and three bugs fixed
 A static review of the v4 golden model (2026-11-02) found, among smaller things, three bugs, fixed
 in `fd208825`: the hosted front end ran the tail of an over-long line as a line of its own; the
 bare-metal line editor cut a line silently at 255 characters and ran it; and a store the node
 itself refuses (to "any port", "which port", How or Have) went on to move A (`!+`) or P (`!p`),
 so `!p` landed in the next fault kind's handler. A regression test (`v4/tests/test_port.c`) fails
 on the old `exec.c`. The rest of the review is filed as issues (section 7).
 ### 2. Logs and DoE CSVs in LFS, as `.gitattributes` always said
 **Found.** 1,003 `.log` and DoE `.csv` files were committed as plain files although
 `.gitattributes` routes them through LFS (3,944 others are pointers), so every fresh clone showed
 them modified. **Built.** `git add --renormalize` (`027b144e`); each pointer's oid is the sha256 of
 the file it replaced. `make init` now runs `git lfs install --local`, the cause being a checkout
 without git-lfs. `master` keeps 23 such files until it is merged.
 ### 3. `make ARCH=<arch>[,...] init`
 Installs what the tree needs on Debian/Ubuntu (`d8e3fa81`, `4cef0431`): the build and disk-image
 tools, git-lfs, the documents' toolchain, and per ISA its QEMU, UEFI firmware and compiler.
 syft 1.52.0 (the version `sbom.spdx` was made with) and Isabelle2025-2 (the version
 `proof/COVERAGE.md` names) are not packaged: downloaded, checked against a SHA-256 in the
 Makefile, kept in `build/cache/`, linked into `/usr/local/bin`. Isabelle publishes no sums; its are
 of the archives as downloaded on 2026-11-06. `INIT_DOCS=0` leaves out TeX, Doxygen and Isabelle.
 Verified: the proofs build from it (`logs/20261106-015650/isabelle`), and so do the book, the
 formal volumes and -- after `5b58b0b1` -- the Doxygen API reference: `fix-doxygen-unicode.py` had
 turned the Unicode characters of Doxygen's own `\doxynewunicodechar` lines into `?`, which
 `newunicodechar` refuses.
 ### 4. The nightlies, the release, Nexus
 `scripts/nightly.sh` is the process, a stage per step, each run the same by hand or by CI:
 `accept <amd64|aarch64|riscv64|stick-high>`, `test-32`, `proofs`, `images`, `publish <url>`,
 `docs`, `publish-docs <url>`. `accept` is `scripts/qemu_session.py zuse` (and `stick_zuse
 --target qemu-stick-high`), one QEMU at a time, in the protocol's order; `stick-high` also refuses
 a run whose three architectures disagree on `dict_hash`. Workflows:
 | Workflow | When | What |
 |---|---|---|
 | `nightly.yml` | 03:00 UTC | acceptance, `test-32`, proofs, images, then `starshipos-snapshots` |
 | `nightly-docs.yml` | 04:00 UTC | the documents, then `starshipos-snapshots` |
 | `release.yml` | a tag `v<LITHOS_VERSION>` | the same, to `starshipos-releases`; a tag naming another version is refused |
 | `acceptance.yml` | every PR into `master` | the acceptance protocol (section 5) |
 | `build.yml` | every push | the board images and `make -C v4 test`; publishes nothing |
 Coordinates, one deploy and one timestamp each (`mvn deploy:deploy-file`, maven-deploy-plugin
 3.1.2, so Maven's snapshot metadata is right):
 - `org.starship:kernelImage` -- classifier `pc` (`StarshipOS.iso`: the ISO the amd64 boot
  booted, byte for byte), `raspi5` (`raspi5.img.xz`, for Raspberry Pi Imager), `milkv`
  (`MilkV.img.xz`, the Mars), `logs` (the run's serial logs, proof log and DoE CSVs).
 - `org.starship:documentation` -- classifier `book`, `vol1`, `vol2`, `vol3`, `api`.
 The classifier is the board, not the ISA as first asked: two aarch64 boards would collide. There
 is no Raspberry Pi 4 image -- there is no BCM2711 port (#26). QEMU boots the aarch64 and riscv64
 kernels, not the Pi 5 and Mars images.
 **Verified** by hand, each stage in order (`deb71fae`, `d185b644`), and both deploys against a
 local `file://` repository: the timestamped files, the POMs, and `maven-metadata.xml` with a
 `snapshotVersion` per classifier. **Not verified:** Nexus itself, which asks a login even to read
 (#17). The first scheduled run is the test.
 ### 5. The gate on `master`
 **Found** (2026-11-06). Every CI job ever run here failed at its first `apt-get`: the runner maps
 `runs-on: ubuntu-latest` to `node:20-bullseye`, Debian 11 -- where one security update would not
 fetch, and which has no `qemu-efi-riscv64` and a far older QEMU and compilers than the Ubuntu 24.04
 everything was tested on. **Built** (`6eadd2f5`): every job names its container,
 `gitea/runner-images:ubuntu-24.04-v26.11.03` (Ubuntu 24.04 with the Node that `actions/checkout`
 and `upload-artifact` run on; the dated tag so an image update cannot change a run). The first
 jobs on it all passed (run 150: the three images, and `make -C v4 test` at both widths).
 `acceptance.yml` (`0fd7648a`) runs `.claude/CLAUDE.md`'s protocol on every PR into `master`,
 through the same `nightly.sh` stages. `acceptance`, `nightly` and `release` share the concurrency
 group `qemu`, so the runner never runs two at once: the one-QEMU rule holds in CI. `master`'s
 branch protection: no push or force push by anyone; merging requires
 `Acceptance / Acceptance (pull_request)`; the PR must be up to date with `master`; no approval while
 there is one developer; the admin override blocked. `.claude/CLAUDE.md`'s Hard Rules say the same.
 ### 6. One repository
 The StarForth repository's `master` (658 commits, last `9aebbb22`, 2026-09-17) was never part of
 LithosAnanke's history. It is kept as the annotated tag `archive/starforth-2026-09-17`, verified
 by a fresh fetch from LithosAnanke (same tip, same 658 commits, same first commit), and the
 repository deleted. It had no issues, pull requests, releases, packages, wiki pages, secrets or
 webhooks.
 The repository itself had been created as `rajames/LithosAnanake`, a typo for the project's name.
 Renamed on the server to `rajames/LithosAnanke` (disk and database, Captain Bob, 2026-11-06), with a
 redirect from the old name, so remotes using it still work. Earlier mentions of
 `admin/LithosAnanake` in the docs record where things were at the time and are left as they are.
 ### 7. Gitea
 Wiki off; description and website (the XWiki) set. Labels in scoped sets -- `kind/` and `priority/`
 exclusive, `area/`, `board/`, `status/`. Milestones `v4.0.0` (JUSTIFICATION.md section 14) and
 `Board bring-up`. Issues #4-#29: the v4 gaps to v4.0.0 (#4-#9), the rest of the review, the CI
 items, the merge (#19), the boards (#26-#29). The project board has no API in this Gitea: it is
 made in the web UI (Projects, Basic Kanban). PR #30 merges `StarForth-v4.0.0` into `master`; its
 four conflicts resolved to the branch's files (`92ca805e`).
 ### 8. Open
 - PR #30's acceptance run (run 153) -- the first QEMU boots on the runner. It merges when green.
 - The first scheduled nightly's publish to Nexus (#17).
 - The Pi 5 and Mars images booted on their boards (#27, #28); a Pi 4 port (#26).
 - Revoke the access token `claude-session-20261106` (Settings, Applications).