Each principle's reference file has a "Migrate to your product" section. If your domain isn't covered, we want your real-world example.
How to submit:
- Open an issue using the "Migration Example" template
- Or submit a PR directly — add your example to the relevant reference file under "Migrate to your product"
What makes a good migration example:
- Specific (not "we used caching" but "we built a 3-level cache with these TTLs")
- Honest about trade-offs (what did you give up?)
- Measurable results when possible (latency dropped X%, alerts reduced Y%)
Found a better way to explain a principle? Have evidence from a production system that strengthens or challenges one? Open an issue or PR.
Factual errors, broken links, unclear writing — PRs welcome, no issue needed.
- Direct, active voice. "Design the lifecycle" not "The lifecycle should be designed."
- Concrete over abstract. Code snippets > prose descriptions.
- No jargon without explanation. If a term needs a glossary entry, explain it inline.
- No emojis in principle content (README is fine).
- Marketing language or promotional content
- Hypothetical examples without real-world evidence
- Vendor-specific tool recommendations disguised as principles
- Changes that add complexity without adding clarity
By contributing, you agree that your contributions will be licensed under MIT.