Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 4 additions & 0 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -176,6 +176,10 @@ generated_from: # only for document intake, section 11

### Allowed values

The machine-readable form of these rules is `tools/schema.json`: CI and the
ApolloKnowledgeBase-Manager wizard both read it. Change a rule there and here
together.

- **type:** `reference`, `guide`, `convention`, `best-practice`, `pitfall`,
`example`, `lesson`
- **status:**
Expand Down
40 changes: 18 additions & 22 deletions tools/check_frontmatter.py
Original file line number Diff line number Diff line change
Expand Up @@ -7,32 +7,28 @@

import yaml

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", "official"}
COMPONENTS = {"cpu-68080", "saga-video-isabelle", "saga-audio-arne",
"saga-dma-anni", "saga-3d-maggie", "libraries", "devs",
"filesys", "commands", "datatypes", "toolchain", "hardware",
"general"}
OSES = {"any", "apolloos-r10", "amigaos-3.9", "amigaos-3.2"}
MODES = {"any", "os-friendly", "os-takeover"}
BOARDS = {"any", "v4-standalone", "v4-unicorn", "v4-icedrake", "v4-manticore",
"v4-firebird"}
from kblib import (HANDLE_RE, ROOT, SCHEMA, content_files, expected_type,
frontmatter, maintainers, read, report)

# The allowed values and patterns come from tools/schema.json, which the
# ApolloKnowledgeBase-Manager wizard reads too.
TYPES = set(SCHEMA["types"])
STATUSES = set(SCHEMA["statuses"])
ORIGINS = set(SCHEMA["origins"])
COMPONENTS = set(SCHEMA["components"])
OSES = set(SCHEMA["oses"])
MODES = set(SCHEMA["modes"])
BOARDS = set(SCHEMA["boards"])
# Kinds of source, highest rank first (CONTRIBUTING.md section 4).
BASES = ["core-developer", "measured", "official", "source-code", "other"]
BASES = list(SCHEMA["bases"])
# "any", one core ("Core 12841"), a range ("Core 12830-12840") or a minimum
# ("Core 12841+").
CORE_RE = re.compile(r"^(any|Core \d+(\+|-\d+)?)$")
REQUIRED = ["title", "type", "owner", "status", "origin", "components",
"applies_to"]
NEEDS_SOURCES = {"reference", "best-practice"}
CORE_RE = re.compile(SCHEMA["core_pattern"])
REQUIRED = list(SCHEMA["required"])
NEEDS_SOURCES = set(SCHEMA["needs_sources"])

KEBAB_RE = re.compile(r"^[a-z0-9]+(-[a-z0-9]+)*\.md$")
LESSON_RE = re.compile(r"^\d{4}-\d{2}-[a-z0-9]+(-[a-z0-9]+)*\.md$")
KEBAB_RE = re.compile(SCHEMA["kebab_pattern"])
LESSON_RE = re.compile(SCHEMA["lesson_pattern"])


def check_values(at, key, allowed):
Expand Down
20 changes: 10 additions & 10 deletions tools/kblib.py
Original file line number Diff line number Diff line change
@@ -1,4 +1,5 @@
"""Shared helpers for ApolloKnowledgeBase CI scripts."""
import json
import os
import re
import sys
Expand All @@ -12,19 +13,18 @@
SKIP_DIRS = {"templates", "seed", "sources", "tools", "skills", "evals",
".github", ".git"}

# The rules live in tools/schema.json, shared with the ApolloKnowledgeBase-
# Manager wizard.
with open(os.path.join(ROOT, "tools", "schema.json"), encoding="utf-8") as _f:
SCHEMA = json.load(_f)

# The four knowledge pillars. Files in a pillar are references, except in
# its best-practices/ and pitfalls/ subfolders.
PILLARS = {"core", "hardware", "os", "toolchain"}
PILLAR_SUBFOLDER_TYPES = {"best-practices": "best-practice",
"pitfalls": "pitfall"}
PILLARS = set(SCHEMA["pillars"])
PILLAR_SUBFOLDER_TYPES = dict(SCHEMA["pillar_subfolder_types"])

# Expected `type` per cross-cutting top-level folder.
FOLDER_TYPES = {
"guides": "guide",
"conventions": "convention",
"examples": "example",
"lessons": "lesson",
}
FOLDER_TYPES = dict(SCHEMA["folder_types"])

MAINTAINERS_FILE = os.path.join(ROOT, ".github", "CODEOWNERS.base")

Expand All @@ -50,7 +50,7 @@ def maintainers():
return set()


HANDLE_RE = re.compile(r"^@?[A-Za-z0-9](?:[A-Za-z0-9-]{0,38})$")
HANDLE_RE = re.compile(SCHEMA["handle_pattern"])

FRONTMATTER_RE = re.compile(r"\A---\n(.*?)\n---\n", re.DOTALL)

Expand Down
87 changes: 87 additions & 0 deletions tools/schema.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,87 @@
{
"comment": "The frontmatter and placement rules of the knowledge base, in one place. Read by tools/check_frontmatter.py and tools/kblib.py (CI) and by the ApolloKnowledgeBase-Manager wizard. Change a rule here, and CONTRIBUTING.md with it.",
"types": {
"reference": "Facts: registers, APIs, behaviour, numbers",
"best-practice": "A technique that makes code faster, smaller or more robust, with evidence",
"pitfall": "A trap: symptom, cause, wrong and right code, evidence",
"guide": "Step-by-step how-to",
"example": "Small, compiling, tested code",
"convention": "A team rule for code or process",
"lesson": "What a project learned, for the lessons loop"
},
"statuses": {
"draft": "Unreviewed",
"reviewed": "Checked by its owner",
"verified": "Tested on real hardware (needs last_verified)",
"deprecated": "Do not use (needs superseded_by)"
},
"origins": {
"human": "Written by a person",
"ai-assisted": "Drafted with an AI",
"official": "Converted from official Apollo documentation (maintainers only)"
},
"components": {
"cpu-68080": "The 68080 CPU, AMMX, FPU",
"saga-video-isabelle": "SAGA video (Isabelle)",
"saga-audio-arne": "SAGA audio (Arne)",
"saga-dma-anni": "SAGA DMA (Anni)",
"saga-3d-maggie": "SAGA 3D (Maggie)",
"libraries": "OS libraries",
"devs": "Devices and drivers",
"filesys": "Filesystems",
"commands": "Shell commands",
"datatypes": "Datatypes",
"toolchain": "ApolloCrossDev: compilers, assembler, libraries",
"hardware": "The V4 boards: connectors, headers, memory",
"general": "Anything else"
},
"oses": {
"any": "Any OS",
"apolloos-r10": "ApolloOS R10",
"amigaos-3.9": "AmigaOS 3.9",
"amigaos-3.2": "AmigaOS 3.2"
},
"modes": {
"any": "Any execution mode",
"os-friendly": "Uses the OS; direct SAGA access only at the developer's discretion",
"os-takeover": "Takes over the machine (games, demos) and restores it on exit"
},
"boards": {
"any": "Every V4 model",
"v4-standalone": "V4 Standalone (SA)",
"v4-unicorn": "V4 UniCorn (UNI, A6000)",
"v4-icedrake": "V4 IceDrake (ICE)",
"v4-manticore": "V4 Manticore (MC)",
"v4-firebird": "V4 Firebird (FB)"
},
"bases": {
"core-developer": "(G) the core developer",
"measured": "(M) measured on V4 hardware",
"official": "(official) official Apollo documentation",
"source-code": "(SRC) source code",
"other": "Anything else"
},
"core_pattern": "^(any|Core \\d+(\\+|-\\d+)?)$",
"core_examples": ["any", "Core 12841", "Core 12830-12840", "Core 12841+"],
"required": ["title", "type", "owner", "status", "origin", "components", "applies_to"],
"needs_sources": ["reference", "best-practice"],
"kebab_pattern": "^[a-z0-9]+(-[a-z0-9]+)*\\.md$",
"lesson_pattern": "^\\d{4}-\\d{2}-[a-z0-9]+(-[a-z0-9]+)*\\.md$",
"handle_pattern": "^@?[A-Za-z0-9](?:[A-Za-z0-9-]{0,38})$",
"pillars": {
"core": "The 68080 and SAGA",
"hardware": "The V4 boards",
"os": "ApolloOS and AmigaOS on V4",
"toolchain": "ApolloCrossDev"
},
"pillar_subfolder_types": {
"best-practices": "best-practice",
"pitfalls": "pitfall"
},
"folder_types": {
"guides": "guide",
"conventions": "convention",
"examples": "example",
"lessons": "lesson"
}
}
Loading