Skip to content

Further Reading

Supplementary sources for OSS maintainers adopting FCC patterns.

Within this repo

  • docs/decisions/ — all 5 Architecture Decision Records. Read them in order for the narrative of key FCC choices.
  • ADR-0001 Plugin System — the interface-versus-vendoring decision.
  • ADR-0002 Persona Schema — the rationale for R.I.S.C.E.A.R.'s ten fields.
  • ADR-0003 Workflow Graphs — graph-based workflow design.
  • ADR-0004 Compliance Framework — the compliance/evidence-graph design.
  • ADR-0005 Evidence Graph — linked-data design for audit artifacts.
  • CLAUDE.md — the running project overview. Treat it as a living index to the codebase.
  • RELEASE_NOTES.md — the full cadence history.
  • CONTRIBUTING.md — contributor onboarding.
  • Makefile — the canonical list of one-command tasks.
  • docs/guidebook/ — 24-chapter treatment. Chapters 2 and 3 are most relevant for maintainers.

External — on documentation

  • The Diátaxis framework (Procida). Four quadrants: tutorials, how-tos, references, explanations. FCC's docs loosely follow this. A readable primer and worth emulating.
  • Google's "What's in a good README?" (various posts). Evergreen.
  • "Docs like Code" (Anne Gentle). The classic on the pattern.
  • "Teach, Don't Tell" (Steve Losh). A short essay on docs voice.

External — on open-source governance

  • "Producing Open Source Software" (Karl Fogel). Still the standard text.
  • "The Maintainer's Guide" (various authors). Shorter modern takes.
  • GitHub's Open Source Guides at opensource.guide. Small, readable, free.
  • CNCF's "Contributor Ladder" patterns. Useful for projects that want explicit progression.

External — on release discipline

  • "Release Engineering" chapter in the Google SRE Book. The production-system perspective.
  • Semantic Versioning 2.0.0 specification. Short.
  • "Semantic Line Breaks". A docs-as-code microcosm worth adopting.

External — on contributor experience

  • "First-Timers-Only" movement. The original pattern for reducing OSS entry cost.
  • CodeTriage. A tool for finding triage opportunities.
  • "The Tyranny of Structurelessness" (Jo Freeman). Pre-dates OSS but describes what happens when a group has implicit hierarchy and no written ceremony. Every maintainer should read once.

External — on sister-project coordination

  • CNCF projects' inter-project dependency patterns — study Kubernetes + kubectl + minikube + kind for a canonical multi-repo ecosystem.
  • Rust's workspace pattern — if you prefer the monorepo alternative.
  • The Electron / Node.js / Chromium release-pipeline pattern — a large-scale example of SHA-pinned upstreams.

Code patterns worth copying

In FCC itself:

  • src/fcc/_resources.py — centralized resource path resolution using importlib.resources. No Path(__file__) chains. Worth copying.
  • src/fcc/scaffold/doc_generator.py — the Jinja2-driven doc generator.
  • Makefile targets — every maintainer task has one.
  • RELEASE_NOTES.md structure — prepended, never rewritten.

In other projects:

  • Rust's cargo new --lib scaffolding.
  • Python's src/ layout (FCC follows it).
  • Go's module layout.
  • Node's npm init starter templates.

Tools worth trying

  • Ruff (Python). Dominant linter.
  • Black (Python). Opinionated formatter.
  • Pre-commit. Hook framework that works across languages.
  • MkDocs-material. Opinionated, ergonomic static site generator.
  • Mermaid CLI. For pre-rendering diagrams.
  • Quarto. Multi-format publishing. Heavier, but pays off at scale.
  • gh (GitHub CLI). Scripts PR operations.

Policies worth adopting

  • Code of Conduct — pick Contributor Covenant 2.x.
  • Security policy (SECURITY.md) — short, with embargo rules.
  • License — usually MIT or Apache-2.0 unless you have a reason for copyleft.
  • CODEOWNERS — maps directories to reviewers.
  • Support policy — how long you maintain old versions. Be explicit even if "no support for older than 1 release" is the policy.

Templates and starter kits

  • GitHub's choosealicense.com — picker for open-source licenses.
  • EthicalSource.dev — templates for community standards.
  • cargo-generate templates (Rust).
  • Cookiecutter templates (Python). FCC itself ships fcc scaffold-vertical-project as a Jinja-driven scaffold.

What to do after this track

Pick one pattern and adopt it this week:

  1. Most impactful for new contributors: Adopted R.I.S.C.E.A.R. role for bug-triager (1 hour).
  2. Most impactful for docs drift: Minimum-viable docs-as-code pipeline (3 hours).
  3. Most impactful for release discipline: Standardized release plan template (1 hour).
  4. Most impactful for cross-repo coordination: SHA-pinned ecosystem registry (half day).

You will feel the return within the next release.

Keeping current

FCC adds patterns over time. Watch the release notes for items labelled "governance," "docs," "release," "contributor." Those are the ones most likely to generate transferable patterns.

Subscribe to the GitHub repository. Open issues labelled discussion. Borrow freely.

Where next

You have reached the end of this track. Choose your first pattern; draft a PR; ship. Return to the index or the getting started page if you need to re-orient.