Contributing
What a reviewable change to Episodic looks like
The project gates hard on architecture, types, and documentation. Knowing which gates apply before starting saves the rework.
What stage the project is at
Early. That changes what kind of contribution is useful.
Phase 1 of 6 is complete and the foundations are settled: the domain model, the persistence layer, the ingestion path, and the service scaffolding. Phases 2 and 4 are in progress. Everything from audio onwards is unimplemented design.
Contributions that harden what exists are easier to land than contributions that start something new, because the new thing usually has a roadmap task describing how it was meant to be approached.
By kind of change
Five routes, each with the thing that most often goes wrong.
| Change | Start with |
|---|---|
| A bug in implemented behaviour | Reproduce it against the current checkout, then add a failing test before the fix. Ingestion, profiles, bindings, and intake are the areas with behaviour to break. |
| A new capability | Find the roadmap task it belongs to first. Work without a roadmap home tends to cross a phase boundary and stall in review. |
| An architectural change | Open a decision record. The import boundaries are enforced in continuous integration, so a change that crosses them fails before review. |
| Documentation | The documentation set has a style guide and a spelling policy, both enforced. Prose is gated like code. |
| Infrastructure or the chart | Exercise the local k3d preview. A chart change that has not been rendered is a guess. |
The gates
Every one runs before a change is reviewable. Running them locally is faster than discovering them in continuous integration.
make check-fmt # formatting
make lint # linters, including the hexagonal boundary check
make typecheck # strict type checking
make test # pytest, behavioural scenarios, and CrossHair contracts
make check-migrations # schema drift between models and migrations
make markdownlint # Markdown lint and the en-GB-oxendict spelling policy
make nixie # Mermaid diagram validation
- Architecture. Import boundaries are a lint rule. A domain module that imports a framework fails the build.
- Complexity. Cyclomatic complexity limits are enforced rather than advisory.
- Types. Type checking runs in strict mode.
- Diagrams. Every Mermaid block is rendered to prove it compiles. A broken diagram fails the build, not the reader.
Conventions that catch people out
Three that are not obvious from reading the code.
Spelling is British with Oxford endings - organize, analyse, colour, centre - enforced in Markdown prose. American spellings are correct only inside code identifiers and API surfaces.
Acronyms are expanded on first use, including ones that feel universal. The documentation set is read by people evaluating the platform, not only by people building it.
Behavioural tests use pytest-bdd. New user-visible behaviour is expected to arrive with a scenario, not only a unit test.
Conduct and reporting
Read before contributing, not after something goes wrong.
Participation in the Episodic community is governed by the df12 Productions Code of Conduct, which is based on the Contributor Covenant and includes the routes for reporting a concern.
Read the Code of Conduct · Contributor guidelines · Developers' guide · Find a roadmap task