cncf / cncf/toc

[Initiative]: Adopter documentation standards (ADOPTERS.md)

Open
#2,229 0 comments 0 reactions 0 assignees View on GitHub
init/not-started kind/initiative needs-triage sub/project-reviews
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.