diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS index 5be8ee9..7588ab4 100644 --- a/.github/CODEOWNERS +++ b/.github/CODEOWNERS @@ -11,9 +11,15 @@ /CONTRIBUTING.md @WDrijver @TuKo1982 /templates/ @WDrijver @TuKo1982 /tools/ @WDrijver @TuKo1982 +/sources/ @WDrijver @TuKo1982 /.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/.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/conventions/.gitkeep b/conventions/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/core/best-practices/.gitkeep b/core/best-practices/.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/pitfalls/.gitkeep b/core/pitfalls/.gitkeep new file mode 100644 index 0000000..e69de29 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/best-practices/.gitkeep b/os/best-practices/.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/os/pitfalls/.gitkeep b/os/pitfalls/.gitkeep new file mode 100644 index 0000000..e69de29 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)