Contributing¶
Welcome to the BLIS contributor guide. This section covers engineering standards, development workflows, and extension recipes for building on BLIS.
Quick Start¶
# Build
go build -o blis main.go
# Test
go test ./...
# Lint (install once: go install github.com/golangci/golangci-lint/v2/cmd/golangci-lint@v2.9.0)
golangci-lint run ./...
All three must pass before submitting a PR. CI runs on every PR (see .github/workflows/ci.yml).
Your First Contribution¶
See CONTRIBUTING.md for a step-by-step walkthrough that adds a trivial admission policy — the lightest extension type (~3 files).
Development Workflows¶
| Workflow | When to Use |
|---|---|
| RFC Template | Large features: writing the tracking issue with holes/surfaces/contracts |
| RFC to Plan | After RFC agreement: encode .archon, create sub-issues |
| PR Workflow | Every PR: worktree → plan → implement → review → commit |
| Hypothesis Experiments | Rigorous experiments to validate simulator behavior |
Extension Recipes¶
Extension Recipes — Step-by-step guides for adding policies, scorers, KV tiers, trace records, and per-request metrics.
Standards¶
| Document | Covers |
|---|---|
| Antipattern Rules (R1-R23) | 23 rules, each tracing to a real bug |
| System Invariants (INV-1-INV-13) | Properties that must always hold |
| Engineering Principles | Separation of concerns, interface design, BDD/TDD |
| Experiment Standards | Hypothesis families, rigor requirements |
| Agent Trust Boundaries | Three trust tiers for agent operations |
Templates¶
| Template | Purpose |
|---|---|
| Design Guidelines | DES foundations, module architecture, extension framework |
| RFC to Plan | Claude prompt: encode .archon from agreed RFC + create sub-issues |