DEVELOPMENT.md

Development Workflow

Schema Management

The C4 annotation schema is the source of truth for what annotations are supported and how they work.

Files

c4-annotations-schema.yaml  ← Edit this (source of truth)
SCHEMA.md                   ← Generated (do not edit directly)
generate_schema_docs.py     ← Generator script

Workflow

1. Edit the schema:

   # Edit the YAML file
   vim c4-annotations-schema.yaml

2. Generate documentation:

   make docs
   # or
   python3 generate_schema_docs.py

3. Commit both files:

   git add c4-annotations-schema.yaml SCHEMA.md
   git commit -m "Add new @c4-foo annotation"

Why YAML + Generated Markdown?

• YAML = Source of truth, easy to edit, supports comments
• Markdown = User-friendly documentation, linkable, renderable on GitHub
• Script = Keeps them in sync automatically

CI Check

In CI, we verify SCHEMA.md is up to date:

make check-docs

This prevents merging PRs where someone forgot to regenerate.

Testing

# Run all tests
pytest

# Run specific test file
pytest tests/test_parser.py

# With coverage
pytest --cov=c4_literate

Building

# Install in development mode
pip install -e .

# Build wheel
python -m build

Documentation

• README.md - Main project README
• SCHEMA.md - Auto-generated annotation reference
• docs/ADR-*.md - Architecture decision records
• USAGE_EXAMPLE.md - Example usage with notes-api
• CONTRIBUTING.md - Contribution guidelines