From 5b44e216942f4a2fadd7eea8ff954e8e2aeb0ed8 Mon Sep 17 00:00:00 2001 From: Willem Drijver Date: Mon, 2 Nov 2026 15:40:10 +0300 Subject: [PATCH 1/2] Create the planned content folder structure Add an index.md to each core/ folder (CPU and the four SAGA chips) stating its scope, planned files and that it has no content yet, and .gitkeep files for the other planned folders so they exist in Git. Co-Authored-By: Claude Opus 5.5 --- .github/CODEOWNERS | 5 ++++ best-practices/core/.gitkeep | 0 best-practices/toolchain/.gitkeep | 0 conventions/.gitkeep | 0 core/cpu-68080/index.md | 43 +++++++++++++++++++++++++++++++ core/saga-3d-maggie/index.md | 41 +++++++++++++++++++++++++++++ core/saga-audio-arne/index.md | 41 +++++++++++++++++++++++++++++ core/saga-dma-anni/index.md | 41 +++++++++++++++++++++++++++++ core/saga-video-isabelle/index.md | 41 +++++++++++++++++++++++++++++ examples/.gitkeep | 0 guides/.gitkeep | 0 lessons/.gitkeep | 0 os/commands/.gitkeep | 0 os/datatypes/.gitkeep | 0 os/devs/.gitkeep | 0 os/filesys/.gitkeep | 0 os/libraries/.gitkeep | 0 pitfalls/core/.gitkeep | 0 pitfalls/toolchain/.gitkeep | 0 19 files changed, 212 insertions(+) create mode 100644 best-practices/core/.gitkeep create mode 100644 best-practices/toolchain/.gitkeep create mode 100644 conventions/.gitkeep create mode 100644 core/cpu-68080/index.md create mode 100644 core/saga-3d-maggie/index.md create mode 100644 core/saga-audio-arne/index.md create mode 100644 core/saga-dma-anni/index.md create mode 100644 core/saga-video-isabelle/index.md create mode 100644 examples/.gitkeep create mode 100644 guides/.gitkeep create mode 100644 lessons/.gitkeep create mode 100644 os/commands/.gitkeep create mode 100644 os/datatypes/.gitkeep create mode 100644 os/devs/.gitkeep create mode 100644 os/filesys/.gitkeep create mode 100644 os/libraries/.gitkeep create mode 100644 pitfalls/core/.gitkeep create mode 100644 pitfalls/toolchain/.gitkeep diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS index 5be8ee9..ae46a35 100644 --- a/.github/CODEOWNERS +++ b/.github/CODEOWNERS @@ -14,6 +14,11 @@ /.github/ @WDrijver @TuKo1982 /.markdownlint.jsonc @WDrijver @TuKo1982 +/core/saga-dma-anni/index.md @WDrijver +/core/saga-3d-maggie/index.md @WDrijver +/core/saga-audio-arne/index.md @WDrijver +/core/saga-video-isabelle/index.md @WDrijver +/core/cpu-68080/index.md @WDrijver /os/apolloos-and-amigaos-on-v4.md @WDrijver /os/apolloos-specific-on-v4.md @WDrijver /os/os-takeover.md @WDrijver diff --git a/best-practices/core/.gitkeep b/best-practices/core/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/best-practices/toolchain/.gitkeep b/best-practices/toolchain/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/conventions/.gitkeep b/conventions/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/core/cpu-68080/index.md b/core/cpu-68080/index.md new file mode 100644 index 0000000..8b5a9c7 --- /dev/null +++ b/core/cpu-68080/index.md @@ -0,0 +1,43 @@ +--- +title: 68080 CPU overview +type: reference +owner: WDrijver +status: draft +origin: ai-assisted +components: [cpu-68080] +applies_to: + core: "any" + os: [any] +sources: + - "Not yet collected" +--- + +## Summary + +The Apollo 68080 CPU, successor of the Motorola 68000 family, with the AMMX SIMD extension. + +**This folder has no content yet.** If your task depends on it, tell the +user that the knowledge base does not cover the 68080 CPU yet. Do not fill the +gap with classic Amiga or 68060 knowledge. + +## Details + +### Planned files + +- `isa.md`: instruction set additions beyond the 68060 +- `ammx.md`: AMMX SIMD instructions and registers +- `pipeline-and-timing.md`: pipeline, cycle counts, pairing rules +- `differences-from-68060.md`: what a 68060 programmer would wrongly assume + +### For contributors + +Check the ApolloCrossDev `Docs/` folder (`AC68080PRM.pdf`, `AMMX/`, `FPU/`, `Integer/`) and the 68080 coding pages on apollo-core.com. Start new files from `templates/files/reference.md`. + +## Differences from AmigaOS / AROS / 68060 + +No content yet. + +## Do / Don't + +- DON'T invent register addresses, bit meanings or instruction behavior for + the 68080 CPU. Say that the knowledge base does not cover it. diff --git a/core/saga-3d-maggie/index.md b/core/saga-3d-maggie/index.md new file mode 100644 index 0000000..35befa4 --- /dev/null +++ b/core/saga-3d-maggie/index.md @@ -0,0 +1,41 @@ +--- +title: SAGA 3D (Maggie) overview +type: reference +owner: WDrijver +status: draft +origin: ai-assisted +components: [saga-3d-maggie] +applies_to: + core: "any" + os: [any] +sources: + - "Not yet collected" +--- + +## Summary + +Maggie, the SAGA 3D chip. + +**This folder has no content yet.** If your task depends on it, tell the +user that the knowledge base does not cover the SAGA 3D (Maggie) yet. Do not fill the +gap with classic Amiga or 68060 knowledge. + +## Details + +### Planned files + +- `registers.md`: register map with offsets, bits and access rules +- One file per feature, for example texture mapping + +### For contributors + +Check the SAGA coding pages on apollo-core.com. Start new files from `templates/files/reference.md`. + +## Differences from AmigaOS / AROS / 68060 + +No content yet. + +## Do / Don't + +- DON'T invent register addresses, bit meanings or instruction behavior for + the SAGA 3D (Maggie). Say that the knowledge base does not cover it. diff --git a/core/saga-audio-arne/index.md b/core/saga-audio-arne/index.md new file mode 100644 index 0000000..71a1f82 --- /dev/null +++ b/core/saga-audio-arne/index.md @@ -0,0 +1,41 @@ +--- +title: SAGA audio (Arne) overview +type: reference +owner: WDrijver +status: draft +origin: ai-assisted +components: [saga-audio-arne] +applies_to: + core: "any" + os: [any] +sources: + - "Not yet collected" +--- + +## Summary + +Arne, the SAGA audio chip. + +**This folder has no content yet.** If your task depends on it, tell the +user that the knowledge base does not cover the SAGA audio (Arne) yet. Do not fill the +gap with classic Amiga or 68060 knowledge. + +## Details + +### Planned files + +- `registers.md`: register map with offsets, bits and access rules +- One file per feature, for example channels or sample formats + +### For contributors + +Check the SAGA coding pages on apollo-core.com. Start new files from `templates/files/reference.md`. + +## Differences from AmigaOS / AROS / 68060 + +No content yet. + +## Do / Don't + +- DON'T invent register addresses, bit meanings or instruction behavior for + the SAGA audio (Arne). Say that the knowledge base does not cover it. diff --git a/core/saga-dma-anni/index.md b/core/saga-dma-anni/index.md new file mode 100644 index 0000000..361792a --- /dev/null +++ b/core/saga-dma-anni/index.md @@ -0,0 +1,41 @@ +--- +title: SAGA DMA (Anni) overview +type: reference +owner: WDrijver +status: draft +origin: ai-assisted +components: [saga-dma-anni] +applies_to: + core: "any" + os: [any] +sources: + - "Not yet collected" +--- + +## Summary + +Anni, the SAGA DMA chip. + +**This folder has no content yet.** If your task depends on it, tell the +user that the knowledge base does not cover the SAGA DMA (Anni) yet. Do not fill the +gap with classic Amiga or 68060 knowledge. + +## Details + +### Planned files + +- `registers.md`: register map with offsets, bits and access rules +- One file per feature, for example transfer modes + +### For contributors + +Check the SAGA coding pages on apollo-core.com. Start new files from `templates/files/reference.md`. + +## Differences from AmigaOS / AROS / 68060 + +No content yet. + +## Do / Don't + +- DON'T invent register addresses, bit meanings or instruction behavior for + the SAGA DMA (Anni). Say that the knowledge base does not cover it. diff --git a/core/saga-video-isabelle/index.md b/core/saga-video-isabelle/index.md new file mode 100644 index 0000000..34129ee --- /dev/null +++ b/core/saga-video-isabelle/index.md @@ -0,0 +1,41 @@ +--- +title: SAGA video (Isabelle) overview +type: reference +owner: WDrijver +status: draft +origin: ai-assisted +components: [saga-video-isabelle] +applies_to: + core: "any" + os: [any] +sources: + - "Not yet collected" +--- + +## Summary + +Isabelle, the SAGA video chip: screen modes and video features. + +**This folder has no content yet.** If your task depends on it, tell the +user that the knowledge base does not cover the SAGA video (Isabelle) yet. Do not fill the +gap with classic Amiga or 68060 knowledge. + +## Details + +### Planned files + +- `registers.md`: register map with offsets, bits and access rules +- One file per feature, for example screen modes or sprites + +### For contributors + +Check the SAGA coding pages on apollo-core.com. Start new files from `templates/files/reference.md`. + +## Differences from AmigaOS / AROS / 68060 + +No content yet. + +## Do / Don't + +- DON'T invent register addresses, bit meanings or instruction behavior for + the SAGA video (Isabelle). Say that the knowledge base does not cover it. diff --git a/examples/.gitkeep b/examples/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/guides/.gitkeep b/guides/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/lessons/.gitkeep b/lessons/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/os/commands/.gitkeep b/os/commands/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/os/datatypes/.gitkeep b/os/datatypes/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/os/devs/.gitkeep b/os/devs/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/os/filesys/.gitkeep b/os/filesys/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/os/libraries/.gitkeep b/os/libraries/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/pitfalls/core/.gitkeep b/pitfalls/core/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/pitfalls/toolchain/.gitkeep b/pitfalls/toolchain/.gitkeep new file mode 100644 index 0000000..e69de29 From 18c1d09dd539c34497574f816177c129b9925852 Mon Sep 17 00:00:00 2001 From: Willem Drijver Date: Mon, 2 Nov 2026 16:16:10 +0300 Subject: [PATCH 2/2] Pillar-first layout, OS best practices and pitfalls, document intake - best-practices/ and pitfalls/ move under each pillar: core/, os/, toolchain/. CI derives the expected type from the path. - os/best-practices/ and os/pitfalls/ are allowed. Only 'works on AmigaOS, fails on ApolloOS' is excluded: that is an ApolloOS.R10 issue. - Document intake for official Apollo documents (maintainers only): the original in sources/official/ is leading, generated files carry origin: official and generated_from, CI checks maintainer ownership. Co-Authored-By: Claude Opus 5.5 --- .github/CODEOWNERS | 1 + .github/CODEOWNERS.base | 1 + AGENTS.md | 41 ++-- CONTRIBUTING.md | 177 +++++++++++++----- README.md | 27 ++- .../core => core/best-practices}/.gitkeep | 0 .../toolchain => core/pitfalls}/.gitkeep | 0 {pitfalls/core => os/best-practices}/.gitkeep | 0 {pitfalls/toolchain => os/pitfalls}/.gitkeep | 0 sources/README.md | 11 ++ sources/official/.gitkeep | 0 templates/files/best-practice.md | 2 +- templates/files/convention.md | 2 +- templates/files/example.md | 2 +- templates/files/guide.md | 2 +- templates/files/lesson.md | 2 +- templates/files/pitfall.md | 2 +- templates/files/reference.md | 2 +- toolchain/best-practices/.gitkeep | 0 toolchain/pitfalls/.gitkeep | 0 tools/check_frontmatter.py | 27 ++- tools/kblib.py | 40 +++- 22 files changed, 246 insertions(+), 93 deletions(-) rename {best-practices/core => core/best-practices}/.gitkeep (100%) rename {best-practices/toolchain => core/pitfalls}/.gitkeep (100%) rename {pitfalls/core => os/best-practices}/.gitkeep (100%) rename {pitfalls/toolchain => os/pitfalls}/.gitkeep (100%) create mode 100644 sources/README.md create mode 100644 sources/official/.gitkeep create mode 100644 toolchain/best-practices/.gitkeep create mode 100644 toolchain/pitfalls/.gitkeep diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS index ae46a35..7588ab4 100644 --- a/.github/CODEOWNERS +++ b/.github/CODEOWNERS @@ -11,6 +11,7 @@ /CONTRIBUTING.md @WDrijver @TuKo1982 /templates/ @WDrijver @TuKo1982 /tools/ @WDrijver @TuKo1982 +/sources/ @WDrijver @TuKo1982 /.github/ @WDrijver @TuKo1982 /.markdownlint.jsonc @WDrijver @TuKo1982 diff --git a/.github/CODEOWNERS.base b/.github/CODEOWNERS.base index 13dc2a0..5abdba0 100644 --- a/.github/CODEOWNERS.base +++ b/.github/CODEOWNERS.base @@ -8,5 +8,6 @@ /CONTRIBUTING.md @WDrijver @TuKo1982 /templates/ @WDrijver @TuKo1982 /tools/ @WDrijver @TuKo1982 +/sources/ @WDrijver @TuKo1982 /.github/ @WDrijver @TuKo1982 /.markdownlint.jsonc @WDrijver @TuKo1982 diff --git a/AGENTS.md b/AGENTS.md index 2a9aa8d..9d16bc2 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -46,7 +46,7 @@ compiler knowledge is where you will make confident mistakes. - DON'T assume generic m68k GCC or vasm behavior. ApolloCrossDev is a patched GCC 6.5 with 68080 support. Check `toolchain/`. - DON'T write generic 68k code when an Apollo-specific technique exists. Check - `best-practices/` before writing performance-relevant code. + `core/best-practices/` before writing performance-relevant code. - DON'T use OS functions that are missing in one of the project's target operating systems. Check `os/apolloos-and-amigaos-on-v4.md`. - DON'T access SAGA registers directly in an `os-friendly` project unless the @@ -62,16 +62,19 @@ compiler knowledge is where you will make confident mistakes. ## 3. What to read for your task -Read only what your task needs. Always check the matching `pitfalls/` and -`best-practices/` subfolders as well as the reference files. +The knowledge base has three pillars: `core/` (68080 and SAGA), `os/` +(ApolloOS and AmigaOS on V4) and `toolchain/` (ApolloCrossDev). Each has its +own `best-practices/` and `pitfalls/` subfolders. Read only what your task +needs, and always check the `best-practices/` and `pitfalls/` of every pillar +you read. | Task | Read | |---|---| -| Any task | This file, `os/apolloos-and-amigaos-on-v4.md` | +| Any task | This file, `os/apolloos-and-amigaos-on-v4.md`, `os/best-practices/`, `os/pitfalls/` | | Target OS is ApolloOS only, or working on ApolloOS itself (ApolloOS.R10) | `os/apolloos-specific-on-v4.md`, `os/` subfolders | -| Execution mode is `os-takeover` (games, demos) | `os/os-takeover.md`, `core/`, `best-practices/core/`, `pitfalls/core/` | +| Execution mode is `os-takeover` (games, demos) | `os/os-takeover.md`, `core/` | | Writing code at all | `conventions/`, `toolchain/` | -| CPU-heavy or assembly code | `core/cpu-68080/`, `best-practices/core/`, `pitfalls/core/` | +| CPU-heavy or assembly code | `core/cpu-68080/`, `core/best-practices/`, `core/pitfalls/` | | Graphics, screens, video modes | `core/saga-video-isabelle/` | | Sound | `core/saga-audio-arne/` | | Memory transfers, DMA | `core/saga-dma-anni/` | @@ -81,7 +84,7 @@ Read only what your task needs. Always check the matching `pitfalls/` and | Filesystems | `os/filesys/` | | Shell commands | `os/commands/` | | Datatypes | `os/datatypes/` | -| Build problems, compiler flags, optimization settings | `toolchain/`, `best-practices/toolchain/`, `pitfalls/toolchain/` | +| Build problems, compiler flags, optimization settings | `toolchain/`, `toolchain/best-practices/`, `toolchain/pitfalls/` | | A task with a matching how-to | `guides/` | | Looking for working code to start from | `examples/` | @@ -108,8 +111,14 @@ Every file starts with YAML frontmatter (full spec in `CONTRIBUTING.md`). that `os` is `any` or covers every target OS of the project, and that `mode` (if present) includes the project's execution mode. If not, or the target is unknown, say so. -- **origin: ai-assisted**: drafted by an AI. Treat like `draft` unless the - status says otherwise. +- **origin** + - `official`: converted from official Apollo documentation. Authoritative, + but conversion errors are possible while the status is `draft`. + - `ai-assisted`: drafted by an AI. Treat like `draft` unless the status + says otherwise. +- **generated_from**: the file is generated from an original document in + `sources/official/`. Never edit it. Propose the change to the maintainers + as a change to the original document. When two files contradict each other, prefer the higher status, then the more recent `last_verified`, and tell the user about the conflict. @@ -123,15 +132,16 @@ recent `last_verified`, and tell the user about the conflict. ApolloCrossDev repository) and say that your answer is based on it. 3. Propose a new knowledge base file or addition so the gap gets closed. -If ApolloOS behaves differently from AmigaOS in a way that breaks a program, -that is an ApolloOS bug. Propose an issue for -github.com/ApolloTeam-dev/ApolloOS.R10, not a knowledge base workaround. +If something works on AmigaOS but fails on ApolloOS, that is an ApolloOS bug. +Propose an issue for github.com/ApolloTeam-dev/ApolloOS.R10, not a pitfall or +workaround in the knowledge base. --- ## 6. Writing code -- Apply relevant `best-practices/` and avoid all relevant `pitfalls/`. +- Apply the relevant best practices and avoid all relevant pitfalls of each + pillar. - Build with ApolloCrossDev as described in `toolchain/`, and fix all errors and warnings before presenting code. - In pull request descriptions, list the knowledge base files you relied on. @@ -143,7 +153,10 @@ github.com/ApolloTeam-dev/ApolloOS.R10, not a knowledge base workaround. ## 7. Writing to the knowledge base - Follow `CONTRIBUTING.md` exactly: folder, file name, frontmatter, template. -- Always set `origin: ai-assisted` and `status: draft`. +- Always set `origin: ai-assisted` and `status: draft`. Exception: during + document intake by a maintainer, set `origin: official` as described in + `CONTRIBUTING.md` section 11. +- Never edit a file that has `generated_from` in its frontmatter. - Set `owner` to the person who asked you to make the change, unless they name someone else. - Never change the `status` of an existing file. Status changes are human diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index b4cffa9..d48cf54 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -10,7 +10,8 @@ AI agents creating or editing files in this repository MUST follow it. 1. **Document the differences.** Do not re-document classic AmigaOS or AROS behavior that is unchanged. Focus on where ApolloOS, the 68080 and the SAGA - chipset differ, extend, or break expectations. + chipset differ, extend, or break expectations. Exception: official + documents (section 11) are converted in full. 2. **One topic per file.** If a file covers two things, split it. 3. **Be exact.** Give register offsets, bit meanings, cycle counts, return values and version numbers. Never write "see the manual". @@ -23,45 +24,55 @@ AI agents creating or editing files in this repository MUST follow it. ## 2. Where things go -| Folder | Contains | Typical `type` | -|---|---|---| -| `core/cpu-68080/` | ISA, AMMX, pipeline, timing, 68060 differences | reference | -| `core/saga-video-isabelle/` | Video chip: modes, registers, features | reference | -| `core/saga-audio-arne/` | Audio chip | reference | -| `core/saga-dma-anni/` | DMA chip | reference | -| `core/saga-3d-maggie/` | 3D chip | reference | -| `os/` | `apolloos-and-amigaos-on-v4.md` (running on V4 under any target OS), `os-takeover.md` (entering and leaving a takeover), `apolloos-specific-on-v4.md` (ApolloOS only: ApolloOS features and differences from AROS) | reference | -| `os/libraries/` | ApolloOS API routines (Libs:) | reference | -| `os/devs/` | ApolloOS device drivers (Devs:) | reference | -| `os/filesys/` | ApolloOS filesystem handlers (L:) | reference | -| `os/commands/` | ApolloOS shell commands (C:) | reference | -| `os/datatypes/` | ApolloOS datatypes (Classes:) | reference | -| `toolchain/` | ApolloCrossDev (github.com/WDrijver/ApolloCrossDev), the single toolchain for all Apollo development: components, setup, compiler and assembler options, syntax | reference | -| `guides/` | Step-by-step how-tos for common tasks | guide | -| `conventions/` | Coding style, toolchain, build, testing, PRs | convention | -| `best-practices/` | How to write optimal code using all V4 features | best-practice | -| `pitfalls/` | Known traps and how to avoid them | pitfall | -| `examples/` | Small, compiling, tested code snippets | example | -| `lessons/` | Raw project retrospectives | lesson | -| `templates/` | File templates per type (`files/`), code-repo templates (`repo/`), seed collection template (`seed/`) | — | -| `skills/` | AI agent skills (see step 2) | — | -| `evals/` | Benchmark tasks for AI evaluation (see step 5) | — | -| `tools/` | CI scripts and generators | — | - -Each chip folder keeps its register map in `registers.md` inside that folder. - -`best-practices/` and `pitfalls/` are split into subfolders that mirror the -reference areas, so related knowledge is easy to find: +The knowledge base has three pillars: **core** (the hardware), **os** (the +operating systems) and **toolchain** (ApolloCrossDev). Each pillar holds +reference files plus its own `best-practices/` and `pitfalls/`. Knowledge +that spans pillars goes in the cross-cutting folders. ```text -best-practices/ -├── core/ # CPU and chipset-level optimization -└── toolchain/ # ApolloCrossDev: flags and settings for optimal output -pitfalls/ -├── core/ -└── toolchain/ +core/ 68080 CPU and SAGA chipset +├── cpu-68080/ ISA, AMMX, pipeline, timing, 68060 differences +├── saga-video-isabelle/ video chip +├── saga-audio-arne/ audio chip +├── saga-dma-anni/ DMA chip +├── saga-3d-maggie/ 3D chip +├── best-practices/ +└── pitfalls/ +os/ ApolloOS R10, AmigaOS 3.9 and 3.2 on Apollo V4 +├── *.md running on V4, OS takeover, ApolloOS specifics +├── libraries/ devs/ filesys/ commands/ datatypes/ ApolloOS components +├── best-practices/ +└── pitfalls/ +toolchain/ ApolloCrossDev +├── *.md components, setup, options, syntax +├── best-practices/ +└── pitfalls/ +guides/ step-by-step how-tos +examples/ small, compiling, tested code +conventions/ team coding style and process +lessons/ project retrospectives ``` +| Folder | `type` | +|---|---| +| `core/`, `os/`, `toolchain/` and their subfolders | reference | +| `/best-practices/` | best-practice | +| `/pitfalls/` | pitfall | +| `guides/` | guide | +| `examples/` | example | +| `conventions/` | convention | +| `lessons/` | lesson | + +Not content: `templates/` (file, repo and seed templates), `sources/` +(original documents for document intake, section 11), `skills/` (AI agent +skills, step 2), `evals/` (AI benchmarks, step 5), `tools/` (CI scripts). + +Each chip folder keeps its register map in `registers.md` inside that folder. + +A best practice or pitfall goes in the pillar it is about. One that spans +pillars goes in the pillar where a developer would look first, with +`related:` links to the others. + Toolchain best practices still need evidence: show the compiler flags or settings, and compare the generated code or measured speed against a baseline. @@ -72,12 +83,18 @@ Apollo V4 software targets the V4 hardware, running ApolloOS R10, AmigaOS the OS. Guidelines for running well on V4 under each OS go in `os/apolloos-and-amigaos-on-v4.md`. -There are no `best-practices/os/` or `pitfalls/os/` folders. Where ApolloOS -behaves differently from AmigaOS in a way that breaks programs, that is an -ApolloOS bug: report it as an issue in +AmigaOS is the leading reference. When something works on AmigaOS but fails +on ApolloOS, that is an ApolloOS bug: report it as an issue in github.com/ApolloTeam-dev/ApolloOS.R10 so it gets fixed in the source. Do not document a workaround in this knowledge base. +Everything else is welcome in `os/best-practices/` and `os/pitfalls/`, with +`applies_to.os` set accordingly: + +- valid on both ApolloOS and AmigaOS on V4: `os: [any]` +- a trap in AmigaOS 3.9 or 3.2 itself: for example `os: [amigaos-3.2]` +- about an ApolloOS-only feature: `os: [apolloos-r10]` + ### Execution mode Every Apollo V4 program starts from an OS and returns to it, in one of two @@ -92,9 +109,10 @@ execution modes: restores multitasking and the Workbench screen. Typical for games and demos. -How to enter and leave a takeover goes in `os/os-takeover.md`. Takeover best -practices and pitfalls go in `best-practices/core/` and `pitfalls/core/`, -with `mode: [os-takeover]` in their frontmatter. +How to enter and leave a takeover goes in `os/os-takeover.md`, with its best +practices and pitfalls in `os/best-practices/` and `os/pitfalls/`. Direct +hardware programming during a takeover goes in `core/`. Both use +`mode: [os-takeover]` in their frontmatter. --- @@ -118,7 +136,7 @@ title: AMMX pixel blending # required, human-readable type: best-practice # required, see allowed values owner: github-handle # required, one GitHub handle status: draft # required, see allowed values -origin: human # required: human | ai-assisted +origin: human # required, see allowed values components: [cpu-68080, saga-video-isabelle] # required, see allowed values applies_to: # required core: "" # use the team's revision notation @@ -127,10 +145,11 @@ applies_to: # required last_verified: 2026-10-31 # required once status is verified tags: [ammx, graphics, blitting] # optional, free keywords for search related: # optional, paths to related files - - pitfalls/ammx-alignment.md + - core/pitfalls/ammx-alignment.md sources: # required for reference, best-practice - "Apollo core spec, section X" superseded_by: # only when status is deprecated +generated_from: # only for document intake, section 11 --- ``` @@ -143,8 +162,12 @@ superseded_by: # only when status is deprecated - `reviewed`: owner has reviewed content - `verified`: tested on real Apollo V4 hardware on the stated core revision - `deprecated`: no longer valid; must name `superseded_by` -- **origin:** `human`, or `ai-assisted` (any AI-drafted content). AI-assisted - files can only move beyond `draft` after a human review. +- **origin:** + - `human`: written by a person + - `ai-assisted`: any AI-drafted content; can only move beyond `draft` + after a human review + - `official`: from official Apollo documentation through document intake + (section 11); maintainers only, CI checks that the owner is a maintainer - **components:** `cpu-68080`, `saga-video-isabelle`, `saga-audio-arne`, `saga-dma-anni`, `saga-3d-maggie`, `libraries`, `devs`, `filesys`, `commands`, `datatypes`, `toolchain`, `general` @@ -206,8 +229,9 @@ don't use. 1. After a project, write `lessons/YYYY-MM-project-name.md` (AI may draft). 2. Lessons stay `draft` and are not read by AI agents by default. -3. Periodically, the team distills recurring points into `best-practices/`, - `pitfalls/` or `guides/`, and links the lesson in their `sources`. +3. Periodically, the team distills recurring points into the pillars' + `best-practices/` or `pitfalls/`, or into `guides/`, and links the lesson + in their `sources`. 4. Distilled lessons stay in place as history. --- @@ -239,8 +263,9 @@ Do not delete outdated files. Set `status: deprecated`, fill in Every pull request runs (scripts in `tools/`): - `check_frontmatter.py`: required fields, allowed values, file naming, - type matches folder, no leftover `` text, `related` and - `superseded_by` paths exist + type matches folder, no leftover `` text, `related`, + `superseded_by` and `generated_from` paths exist, `official` files are + owned by a maintainer - `check_links.py`: internal markdown links point to existing files - `check_owners.py`: every owner is an existing GitHub account - Markdown lint (rules in `.markdownlint.jsonc`) @@ -252,7 +277,8 @@ On every merge to `main`, `generate_codeowners.py` regenerates `.github/CODEOWNERS`. Fixed owners for files without frontmatter go in `.github/CODEOWNERS.base`. -The `seed/` and `templates/` folders are excluded from content checks. +The `seed/`, `sources/` and `templates/` folders are excluded from content +checks. Run the checks locally before opening a pull request: @@ -261,3 +287,52 @@ pip install pyyaml python tools/check_frontmatter.py python tools/check_links.py ``` + +--- + +## 11. Document intake (maintainers only) + +Official Apollo documentation, such as the Apollo 68080 Programmer's +Reference Manual, enters the knowledge base through document intake. Only +the maintainers (WDrijver and TuKo1982, the default owners in +`.github/CODEOWNERS.base`) use this route. + +**The original document is leading**, unless the intake PR states otherwise. +Updates to the original are expected, and each one goes through the intake +steps again. Never edit generated files by hand: change the original and +regenerate. + +### Steps + +1. Add or update the original in `sources/official/`, in an editable format + such as ODT. PDF is a last resort. +2. Convert it to Markdown, for example with pandoc. +3. Optimize for AI (see below) and split it into knowledge base files in the + right pillar. Every generated file gets: + - `origin: official` + - `owner`: a maintainer + - `status: draft` + - `generated_from: sources/official/` +4. Open a PR. The maintainer checks the conversion against the original and + sets `status: reviewed` when it is correct. +5. On an update of the original: repeat steps 1–4, and review the diff of + the generated files. + +When the PR states that the Markdown becomes leading instead, leave out +`generated_from` and remove the original from `sources/official/`. From then +on, the files are edited like any other file. + +### Optimized for AI + +- Markdown files of at most ~400 lines, one topic per file. A large manual + becomes a folder with an `index.md` that maps topics (for example + mnemonics) to files. +- The same structure for every entry of the same kind, for example every + instruction with syntax, operation, sizes, condition codes, encoding and + cycles. +- Facts in tables: registers, opcodes, timing. +- No facts only in images. Describe every diagram or timing chart in text. +- Code blocks with a language tag, cross-references as `related:` links. +- Differences from the 68000/68060 or AmigaOS called out explicitly. +- Anything that did not convert cleanly is listed in the PR, not silently + dropped. diff --git a/README.md b/README.md index 257a2e8..7f37b4c 100644 --- a/README.md +++ b/README.md @@ -13,19 +13,30 @@ the platform correctly and to its full potential. ## What's inside -| Folder | Contents | +Three pillars of knowledge, each with reference files, best practices and +pitfalls: + +| Pillar | Contents | |---|---| | `core/` | 68080 CPU and the SAGA chips: Isabelle (video), Arne (audio), Anni (DMA), Maggie (3D) | -| `os/` | Running on V4 under ApolloOS R10, AmigaOS 3.9 and 3.2; ApolloOS internals (differences from AROS, libraries, devs, filesys, commands, datatypes) | +| `os/` | Running on V4 under ApolloOS R10, AmigaOS 3.9 and 3.2; OS takeover; ApolloOS internals (libraries, devs, filesys, commands, datatypes) | | `toolchain/` | ApolloCrossDev setup, options and syntax | -| `best-practices/` | How to write optimal code using all Apollo V4 features | -| `pitfalls/` | Known traps and how to avoid them | + +Each pillar has `best-practices/` (how to write optimal code using all Apollo +V4 features) and `pitfalls/` (known traps and how to avoid them). + +Cross-cutting folders: + +| Folder | Contents | +|---|---| | `guides/` | Step-by-step how-tos | | `examples/` | Small, compiling, tested code | | `conventions/` | Team coding style and process | | `lessons/` | Project retrospectives | -| `templates/` | Templates for new knowledge base files, for code repositories, and for collecting seed content | -| `skills/`, `evals/`, `tools/` | AI agent skills, AI benchmarks, CI scripts | + +Supporting folders: `templates/` (templates for knowledge base files, code +repositories and seed content), `sources/` (original official documents), +`tools/` (CI scripts), and later `skills/` and `evals/`. Each file shows its owner, its status (`draft`, `reviewed`, `verified`, `deprecated`) and which core revision, target OS and execution mode @@ -62,7 +73,7 @@ the file format and review process. The most valuable contributions are: - Places where ApolloOS, the 68080 or SAGA differ from what developers (and AI models) expect -- Measured optimization techniques for `best-practices/` -- Bugs you hit and how you fixed them, for `pitfalls/` +- Measured optimization techniques, for the pillars' `best-practices/` +- Bugs you hit and how you fixed them, for the pillars' `pitfalls/` AI agents: start with `AGENTS.md`. diff --git a/best-practices/core/.gitkeep b/core/best-practices/.gitkeep similarity index 100% rename from best-practices/core/.gitkeep rename to core/best-practices/.gitkeep diff --git a/best-practices/toolchain/.gitkeep b/core/pitfalls/.gitkeep similarity index 100% rename from best-practices/toolchain/.gitkeep rename to core/pitfalls/.gitkeep diff --git a/pitfalls/core/.gitkeep b/os/best-practices/.gitkeep similarity index 100% rename from pitfalls/core/.gitkeep rename to os/best-practices/.gitkeep diff --git a/pitfalls/toolchain/.gitkeep b/os/pitfalls/.gitkeep similarity index 100% rename from pitfalls/toolchain/.gitkeep rename to os/pitfalls/.gitkeep diff --git a/sources/README.md b/sources/README.md new file mode 100644 index 0000000..e3021a3 --- /dev/null +++ b/sources/README.md @@ -0,0 +1,11 @@ +# sources + +Original documents for document intake (see `CONTRIBUTING.md` section 11). +Maintainers only. + +- `official/`: official Apollo documentation in an editable format, such as + ODT. The original is leading: knowledge base files generated from it carry + `generated_from: sources/official/` and are never edited by hand. + +This folder is not knowledge base content. AI agents read the generated +files, not these originals. diff --git a/sources/official/.gitkeep b/sources/official/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/templates/files/best-practice.md b/templates/files/best-practice.md index 95005c1..dec24fe 100644 --- a/templates/files/best-practice.md +++ b/templates/files/best-practice.md @@ -3,7 +3,7 @@ title: type: best-practice owner: status: draft -origin: +origin: components: [] applies_to: core: "" diff --git a/templates/files/convention.md b/templates/files/convention.md index ce57061..dc6fb63 100644 --- a/templates/files/convention.md +++ b/templates/files/convention.md @@ -3,7 +3,7 @@ title: type: convention owner: status: draft -origin: +origin: components: [] applies_to: core: "" diff --git a/templates/files/example.md b/templates/files/example.md index 22ac801..1d845c9 100644 --- a/templates/files/example.md +++ b/templates/files/example.md @@ -3,7 +3,7 @@ title: type: example owner: status: draft -origin: +origin: components: [] applies_to: core: "" diff --git a/templates/files/guide.md b/templates/files/guide.md index ee34ad1..08193b0 100644 --- a/templates/files/guide.md +++ b/templates/files/guide.md @@ -3,7 +3,7 @@ title: type: guide owner: status: draft -origin: +origin: components: [] applies_to: core: "" diff --git a/templates/files/lesson.md b/templates/files/lesson.md index 607e5f6..b0acc8a 100644 --- a/templates/files/lesson.md +++ b/templates/files/lesson.md @@ -3,7 +3,7 @@ title: type: lesson owner: status: draft -origin: +origin: components: [] applies_to: core: "" diff --git a/templates/files/pitfall.md b/templates/files/pitfall.md index 38c10e2..253c3ae 100644 --- a/templates/files/pitfall.md +++ b/templates/files/pitfall.md @@ -3,7 +3,7 @@ title: type: pitfall owner: status: draft -origin: +origin: components: [] applies_to: core: "" diff --git a/templates/files/reference.md b/templates/files/reference.md index a697dd1..d2ff30d 100644 --- a/templates/files/reference.md +++ b/templates/files/reference.md @@ -3,7 +3,7 @@ title: type: reference owner: status: draft -origin: +origin: components: [] applies_to: core: "" diff --git a/toolchain/best-practices/.gitkeep b/toolchain/best-practices/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/toolchain/pitfalls/.gitkeep b/toolchain/pitfalls/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/tools/check_frontmatter.py b/tools/check_frontmatter.py index 8e89f44..5216b6d 100644 --- a/tools/check_frontmatter.py +++ b/tools/check_frontmatter.py @@ -7,12 +7,13 @@ import yaml -from kblib import FOLDER_TYPES, HANDLE_RE, ROOT, content_files, frontmatter, read, report +from kblib import (HANDLE_RE, ROOT, content_files, expected_type, frontmatter, + maintainers, read, report) TYPES = {"reference", "guide", "convention", "best-practice", "pitfall", "example", "lesson"} STATUSES = {"draft", "reviewed", "verified", "deprecated"} -ORIGINS = {"human", "ai-assisted"} +ORIGINS = {"human", "ai-assisted", "official"} COMPONENTS = {"cpu-68080", "saga-video-isabelle", "saga-audio-arne", "saga-dma-anni", "saga-3d-maggie", "libraries", "devs", "filesys", "commands", "datatypes", "toolchain", "general"} @@ -53,8 +54,9 @@ def check(path): errs = [] name = os.path.basename(path) top = path.split(os.sep)[0] + expected = expected_type(path) - if top not in FOLDER_TYPES: + if expected is None: return [f"file is outside the known content folders ({top}/)"] if top == "lessons": @@ -81,9 +83,9 @@ def check(path): if t is not None: if t not in TYPES: errs.append(f"invalid type '{t}'") - elif t != FOLDER_TYPES[top]: - errs.append(f"type '{t}' does not belong in {top}/ " - f"(expected '{FOLDER_TYPES[top]}')") + elif t != expected: + errs.append(f"type '{t}' does not belong in " + f"{os.path.dirname(path)}/ (expected '{expected}')") owner = fm.get("owner") if owner is not None and not (isinstance(owner, str) @@ -98,6 +100,19 @@ def check(path): if origin is not None and origin not in ORIGINS: errs.append(f"invalid origin '{origin}'") + # Document intake (CONTRIBUTING.md section 11) is for maintainers only. + if origin == "official" and isinstance(owner, str) \ + and owner.lstrip("@") not in maintainers(): + errs.append("origin 'official' requires a maintainer as owner") + gf = fm.get("generated_from") + if gf is not None: + if origin != "official": + errs.append("generated_from requires origin 'official'") + if not (isinstance(gf, str) and gf.startswith("sources/official/")): + errs.append("generated_from must be a path in sources/official/") + elif not os.path.isfile(os.path.join(ROOT, gf)): + errs.append(f"generated_from points to missing file '{gf}'") + if t == "lesson" and status not in (None, "draft", "deprecated"): errs.append("lessons stay draft (or deprecated)") diff --git a/tools/kblib.py b/tools/kblib.py index a09ad02..a2f9cda 100644 --- a/tools/kblib.py +++ b/tools/kblib.py @@ -9,21 +9,47 @@ # Top-level files and folders that are not knowledge base content. SKIP_TOP_FILES = {"README.md", "AGENTS.md", "CONTRIBUTING.md", "CLAUDE.md"} -SKIP_DIRS = {"templates", "seed", "tools", "skills", "evals", ".github", ".git"} +SKIP_DIRS = {"templates", "seed", "sources", "tools", "skills", "evals", + ".github", ".git"} -# Expected `type` per top-level content folder. +# The three knowledge pillars. Files in a pillar are references, except in +# its best-practices/ and pitfalls/ subfolders. +PILLARS = {"core", "os", "toolchain"} +PILLAR_SUBFOLDER_TYPES = {"best-practices": "best-practice", + "pitfalls": "pitfall"} + +# Expected `type` per cross-cutting top-level folder. FOLDER_TYPES = { - "core": "reference", - "os": "reference", - "toolchain": "reference", "guides": "guide", "conventions": "convention", - "best-practices": "best-practice", - "pitfalls": "pitfall", "examples": "example", "lessons": "lesson", } +MAINTAINERS_FILE = os.path.join(ROOT, ".github", "CODEOWNERS.base") + + +def expected_type(path): + """Return the `type` a content file must have, from its folder, or None + if the file is outside the known content folders.""" + parts = path.split(os.sep) + if parts[0] in PILLARS: + if len(parts) > 2 and parts[1] in PILLAR_SUBFOLDER_TYPES: + return PILLAR_SUBFOLDER_TYPES[parts[1]] + return "reference" + return FOLDER_TYPES.get(parts[0]) + + +def maintainers(): + """Return the maintainer handles: the owners of `*` in CODEOWNERS.base.""" + with open(MAINTAINERS_FILE, encoding="utf-8") as f: + for line in f: + fields = line.split() + if fields and fields[0] == "*": + return {h.lstrip("@") for h in fields[1:]} + return set() + + HANDLE_RE = re.compile(r"^@?[A-Za-z0-9](?:[A-Za-z0-9-]{0,38})$") FRONTMATTER_RE = re.compile(r"\A---\n(.*?)\n---\n", re.DOTALL)