Hacktoberfest 2026: the issues maintainers tagged for October, open and beginner-friendly. Browse Hacktoberfest issues

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

Open
  • Is something wrong?
#2,229 0 comments 0 reactions 0 assignees View on GitHub

Maintainers usually reply within 1 day

Nobody has claimed this yet.

Assessment

Difficulty
5/5
Estimated time
Over a week
Newbie friendliness
25/100
Issue type
Documentation
Clarity
Needs clarification
Activity status
Quiet
Domain
documentation

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.

Description

init/not-started kind/initiative needs-triage sub/project-reviews
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 (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 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

Dominant language
HTML
Stars
1.9k
Forks
728
Avg merge
3d 23h
Merged PRs (30d)
10

Getting set up

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from cncf/toc

All issues in cncf/toc

Similar issues

More Documentation issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.