Templates
On this page
This page holds the skeleton of each kind of document. To start a document, copy the skeleton into a new file in both languages. The sentence under each heading says what belongs there; replace it. A section that does not apply stays, with one line saying why.
The metadata fields are defined in Documentation system.
Capability page
A capability page lives in product/. It describes one thing the product does, from the user’s side.
---
title: Name of the capability
status: draft
created: YYYY-MM-DD
---
One paragraph: what the capability is and whom it serves.
## Problem and evidence
What goes wrong today, with links to research and field notes.
## Scenarios
The numbered scenarios this capability serves.
## Behavior
Rules written as statements that can be checked. Each rule has an example.
## States
The states an object moves through, and what causes each move.
## Surfaces
What the user sees and does on each device.
## Out of scope
What this capability does not do.
## Depends on
The kernel capabilities it relies on, with links to architecture and specifications.
## Open questions
What is not yet decided.
Version design
A version design lives in versions/.
---
title: vX.Y
status: planning
created: YYYY-MM-DD
---
One sentence: the theme of this version.
## Scenarios
The scenarios that must hold after this version. They are also the acceptance script.
## In and out
What this version does, and what it deliberately leaves out.
## Changes to product design
Each change, with a link to the product page it changes.
## Technical work
The RFCs this version needs.
## Risks and open questions
What could go wrong, and what is not yet decided.
## Exit criteria
How we know the version is done.
## Retrospective
Written after shipping: what differed from the plan, and what was learned.
RFC
An RFC lives in rfcs/. The process is in RFC process.
---
title: Short name of the decision
rfc: 0
status: draft
created: YYYY-MM-DD
affects:
- specs/example.md
---
## Summary
One paragraph: what is proposed.
## Motivation
The scenario this serves, the evidence, and what happens if nothing is done.
## Goals and non-goals
What the decision must achieve, and what it does not try to achieve.
## Prior art
What others do. Link to research; do not restate it.
## Proposal
The idea, the key invariants, and one or two examples. The exact text is in the affected pages.
## Alternatives considered
Each alternative, and why it was not chosen.
## Compatibility and migration
What existing behavior, data or documents are affected, and how they move.
## Security and privacy
What the decision exposes or protects.
## Drawbacks and risks
What this costs, and what could go wrong.
## Verification
How we will know it is correct.
## Open questions
Empty, or each question deferred with a reason, before acceptance.
## Implementation
The order of work, and the pages and files to read first.
Specification page
A specification page lives in specs/. It is written for someone implementing it outside the project. It uses the words “must”, “should” and “may” for requirements.
---
title: Name of the protocol, format or API
status: draft
created: YYYY-MM-DD
---
One paragraph: what this specifies and who implements it.
## Stability and version
Whether this is experimental or stable, and its version. Only stable parts carry a compatibility commitment.
## Problems with the status quo
What cannot be done today, or is done badly.
## Quick start
One example that can be run as written.
## Terms and invariants
The words this page uses, and what always holds.
## Format and semantics
The exact format, and what each part means.
## Detection and fallback
How a program finds out whether this is supported, and what happens where it is not.
## Relation to existing protocols
How this fits with what terminals and agents already use.
## Security considerations
What an attacker could do, and what limits it.
## Examples and test vectors
Inputs with their expected results.
## Known implementations
Programs that implement this.
Architecture page
An architecture page lives in architecture/.
---
title: Name of the component or mechanism
status: draft
created: YYYY-MM-DD
---
One paragraph: what this part does and where it sits.
## Compatibility policy
What must keep working, and what may break.
## Goals and non-goals
What this part must achieve, and what it does not try to achieve.
## Concepts and invariants
The objects involved, and what always holds.
## Execution traces
Step-by-step traces of the main paths, including the points where a crash can happen and how recovery proceeds.
## Interfaces and implementation
The interfaces this part offers, and how it is built.
## Open questions
What is not yet decided.
## Testing strategy
How correctness is checked.
## Required reading
The pages and files to read before working on this part, in order.
Research note
A research note lives in one of the folders of research/.
---
title: The question, or the subject
created: YYYY-MM-DD
as_of: YYYY-MM-DD
---
One paragraph: the question and the short answer.
## Findings
The facts. Each claim carries its reliability: official, vendor, or third party.
## What this means for cotty
The consequences for product or technical design.
## Sources
Links to everything used.
## Not covered
What was not looked at.
Post
A post lives in posts/.
---
title: The claim, or the subject
created: YYYY-MM-DD
---
One paragraph: the claim, and why it matters to cotty.
## The argument
One section for each step, named by what it says. A fact that has a date belongs in a research note, and the post links to it.
## What we take from this
What follows for cotty, with links to the state documents.
## References
Links to everything the post relies on.