Circulation
A man with a watch knows what time it is. A man with two watches is never sure.
— Segal’s law
Circulation aims for the discoverability of contracts. It relies on specifications to define contracts, registries to serve specifications to machines, and portals to expose contracts to people.
Concerns
Section titled “Concerns”- Tribal knowledge occurs when teams neglect to describe contracts in specifications. This delays integration due to contracts that exist only in code and in people’s heads.
- Split brain occurs when teams neglect to keep every version of a specification in one authoritative place. This delays development due to pipelines and runtimes that consume conflicting or outdated copies.
- Hidden contracts occur when teams neglect to expose contracts to people outside the owning team. This increases duplication due to teams rebuilding APIs they cannot find.
Actions
Section titled “Actions”- Publish specifications to describe contracts.
- Adopt registries to serve every version of a specification to machines from one authoritative place.
- Adopt portals to expose contracts to people, alongside the services and teams that own them.