CNCF 项目元数据怎样统一维护治理入口

CNCF 项目可以把 .project 仓库作为结构化元数据入口：用 project.yaml 统一记录治理文档等引用，用 maintainers.yaml 记录维护者账号与团队关系，并通过受审阅的变更维护。治理规则正文仍由项目自己的文档承载；统一入口并不意味着所有文档、个人资料与下游页面都会自动同步。

官方地址：https://github.com/cncf/automation/tree/main/utilities/dot-project

CNCF 在2026年4月22日介绍了 .project 推广安排。本文解读其当前文档中的维护方式，围绕多仓库项目的治理入口展开，不把早前公告写成最新发布，也不提供未经测量的上线收益。

仓库变多后，治理入口为什么容易失配

考虑一个拥有核心代码、文档、插件和社区仓库的项目。新贡献者想知道如何成为维护者，可能从README找到旧链接，又在社区仓库看到另一份名单。问题通常不只是“缺少一个网页”，而是多个地方各自保存同一信息，却没有明确谁负责修改。

继续增加一份汇总表，短期可以改善查找，长期却可能再增加一个失配点。更合适的架构是：治理规则有明确正文来源，元数据保存可供自动化读取的入口，维护者对变更负责，下游按自己的流程消费这些记录。

.project 的价值在于标准化项目描述、仓库、治理与联系人等信息，使工具不必猜测每个项目把文档放在哪里。它本身不决定项目采用怎样的投票制度，也不替代项目的治理决定。

把元数据索引与治理正文分开维护

先找出真实有效的治理文件，再把引用登记到对应字段。不要为填满字段而把不存在的路径写进去，也不要把一个通用README同时当作所有治理问题的答案。

这些引用字段采用 PathRef 结构，具体地址放在 path 中。官方模式文档建议新仓库使用完整GitHub URL，减少跨仓库引用的歧义；不能把所有入口都当作无结构字符串随意填写。

例如治理文件从代码仓库迁到社区仓库，应该先明确新的正文归属，再调整索引引用，并处理仍指向旧位置的文档链接。索引的维护目标是让人和工具找到同一份规则，而不是把正文复制多份。

维护者名单与身份资料各管哪一部分

维护者名单是另一个容易混淆的部分。官方工具说明区分了账号和身份信息：maintainers.yaml 管理GitHub handles与团队；维护者姓名、主要邮箱和所属组织等资料来自LFID个人资料。同时，项目公开维护者或治理文档中的组织信息仍需维护。

因此，“改一个文件就全部更新”并不成立。账号更名、团队变动、所属组织变更，可能涉及不同记录，负责人应按变更类型逐项处理，避免只更新最容易看到的一处。

CODEOWNERS 有助于指定审阅责任，但实际是否阻止未经审阅的合并，还取决于仓库保护规则。名单记录、代码审阅权限和项目治理角色也不是天然相同的概念。

用一次变更贯通入口与下游消费

建议把治理入口变更作为一个可审阅的提交处理。提交说明写清楚旧入口为什么变化、新入口由谁维护、是否涉及维护者名单以及哪些下游信息需要跟进。这样审阅者面对的是完整的变更意图，不是一串脱离背景的URL替换。

CNCF 官方介绍说明初始推广由工作人员创建和初始化仓库。项目如果尚未收到对应仓库，应依据当前推广安排与项目团队沟通，不必另起一个同名但无人消费的“元数据中心”。已有仓库中的自动探测内容则需要维护者确认，不能因它由工具生成就认为事实必然正确。

元数据变更可以驱动Landscape更新提案，但提案产生、目标仓库接受和页面展示是不同状态。不要把源仓库合并完成，直接记录成所有下游已更新。本文只说明项目维护流程，没有运行任何工具、发起PR或更改外部项目。

如何判断统一维护真正起作用

评估效果时，可以关注三类信号：新贡献者是否能从统一入口找到现行规则，维护者变动是否有明确责任人，下游记录是否能追溯到一次已接受的元数据变更。这些是建议观察的项目，不是本文声称已经实现的指标。

项目规模继续增长时，还需区分“一个项目有许多仓库”和“一个GitHub组织有多个独立CNCF项目”。当前工具文档提供以 org.yaml 为索引的多项目布局；不能只因为代码仓库数量多就把一个项目拆成多个项目元数据。

project.yaml能替代GOVERNANCE.md吗？不能。前者登记结构化入口，后者说明规则正文。

改了maintainers.yaml就能改个人邮箱吗？不能这样理解。个人资料和项目账号团队记录分属不同维护位置。

统一治理入口是否意味着统一治理制度？不是。标准化的是描述与发现方式，具体职责和决策制度仍由项目自身文件说明。

参考：CNCF .project 推广介绍；官方工具说明；元数据模式说明；公开项目仓库示例。