[Initiative]: Adopter documentation standards (ADOPTERS.md)
- Dominant language
- HTML
- Stars
- 1.9k
- Forks
- 724
- Avg merge
- 6d 12h
- Merged PRs (30d)
- 4
Description
### Name
Adopter documentation standards (ADOPTERS.md)
### Short description
Standardize ADOPTERS.md format with recommended fields so projects, DD reviewers, and adopters have consistent expectations.
### Responsible group
TOC
### Does the initiative belong to a subproject?
Yes
### Subproject name
Project Reviews
### Primary contact
TBD
### Additional contacts
@angellk (TOC Chair, DD finding source)
### Origin
DD finding (automated)
### Initiative description
**This initiative is a request from the TOC.** During due diligence reviews, the TOC evaluates projects against incubation and graduation criteria. When the same finding appears across multiple projects, it signals an ecosystem-wide gap that would be better addressed through standardized guidance than repeated per-project recommendations.
This finding has appeared in **41 of 42 DD reports** (98%) scanned over the last 5 years, including cncf/toc#2198 (HAMi), cncf/toc#2057 (Kyverno), cncf/toc#2050 (Tekton), cncf/toc#2038 (Microcks), cncf/toc#1919 (Crossplane), cncf/toc#1468 (wasmCloud), cncf/toc#1454 (Dapr), and others. The most recent DD to surface this was [HAMi incubation DD](https://github.com/cncf/toc/pull/2198) (merged 2026-07-02).
DDs routinely recommend indicating adoption level (prod/dev/trial) on public adopter lists, reconciling website adopter pages with `.project` ADOPTERS.md files, and standardizing the fields included. There is no current template or guidance for how projects should structure their ADOPTERS.md files. See the [FAQ adopter definition](https://github.com/cncf/toc/blob/main/FAQ.md#what-is-the-definition-of-an-adopter) for adopter categories.
**Scope:** Define a recommended ADOPTERS.md template with fields for organization, industry/vertical, adoption level (prod/dev/trial), use case summary, and date added. Align with the FAQ adopter definition and adopter categories (End-User member, end user, Service Provider, Consultancy, another project).
**Timeline:** TBD
### Deliverable(s) or exit criteria
- [ ] ADOPTERS.md template with recommended fields (org, industry, adoption level, use case, date)
- [ ] Guidance document: adopter documentation best practices
- [ ] DD checklist item update — PR to incubation and graduation application templates
### Tracking document for meeting and progress
TBD
Contributor guide
Research direction
Start with FAQ.md, especially the adopter definition and categories, then review the linked due-diligence findings for recurring requirements. Define the ADOPTERS.md template, best-practices guidance, and the required application-template checklist update; done means all three deliverables are documented and aligned.
Written by the indexing model from the issue text.
Assessment
- Domain
- documentation
- Issue type
- Documentation
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Quiet
- Clarity
- Needs clarification
- Newbie friendliness
- 25/100