CNCF 项目元数据标准化将怎样影响生态目录维护

如果你负责维护 CNCF 项目的生态目录，最近看到组织里多出一个名为 .project 的仓库，不必把它当成普通业务代码仓库。CNCF 正在把项目详情、仓库列表、维护者、治理引用和安全联系人等信息收拢到一个机器可读入口，后续由自动化消费并同步到 Landscape、治理审计和维护者名册等下游位置。

官方公告：https://contribute.cncf.io/blog/2026/04/22/introducing-dot-project-for-maintainers/

这次标准化到底改变了什么

过去，一个项目的官网、README、治理文档、维护者名单和安全策略可能分别由不同人更新。目录维护者为了改一个仓库地址，往往还要手工同步项目目录、Landscape 和内部表格。`.project` 的价值在于提供一份结构化的单一事实源，让 CNCF 自动化读取相同字段，而不是从多份文档里猜测项目状态。

这不是把所有项目内容搬到一个仓库，也不是要求项目立即迁移源码。它更像一层元数据适配层：源码仓库继续承载代码，治理文件继续保留在项目自己的位置，而目录、审计和名单服务读取经过约定格式整理的项目资料。

生态目录维护会受到哪些直接影响

因此，目录维护的工作重心会从“改页面”转向“维护字段契约”。页面没有变化时不代表变更失败；反过来，页面已经变化也不代表源数据一定完整，仍要核对生成结果是否来自正确字段。

接入或收到新仓库后的处理步骤

1. 先确认来源。查看仓库说明和组织归属，确认它是 CNCF 为项目创建的 `.project`，不要再建立一份平行元数据仓库。
2. 做一次字段盘点。把项目名称、官网、代码仓库、维护者、治理文档和安全策略逐项与现有目录比较，记录“源字段—下游位置—责任人”。
3. 小步提交。一次只修一组相关字段，保留 PR 标题、评审人和变更前后值。这样目录出现异常时，可以准确定位是哪次元数据变更触发的。
4. 同步后复核。检查 Landscape、项目目录、维护者列表和安全联系入口，不要只看某一个页面；至少确认链接可达、名称一致、联系人没有被误替换。

目录出现错误时如何排查和回滚

排查顺序建议固定为“源字段、变更记录、同步结果”。先确认错误值是否已经写入 `.project`；如果源字段正确，再检查下游同步是否延迟或映射错误；如果只在某一个展示页面错误，不要直接改展示页覆盖源数据。

回滚时优先恢复最近一次引入错误的元数据提交，并在 PR 中写清受影响的下游位置。对于维护者名册和安全联系人，回滚后还要重新确认责任人和报告渠道。CNCF 当前的安全联系页面已经把项目的安全策略和漏洞报告入口与 `.project` 元数据关联起来，这说明安全字段不是装饰性目录信息，而是会影响实际协作入口的运营数据。

常见问题

.project 会替代项目自己的 README 或 SECURITY.md 吗？

不会。它主要统一供 CNCF 自动化消费的项目元数据；项目文档和安全策略仍应保留在项目自己的仓库中，并让元数据引用指向正确位置。

维护者需要立即手动创建或配置仓库吗？

按照 CNCF 的 rollout 说明，首轮由 CNCF staff 创建和 bootstrap。收到仓库后先阅读说明、核对字段和责任边界，不要因为看到新仓库就重复创建。

目录页面没有及时更新，应该直接手工修改页面吗？

不建议。先确认源字段和同步记录；直接修改下游页面会制造下一次同步时被覆盖的漂移。

这对项目维护流程的最大收益是什么？

把“同一信息在多处手工维护”变成“源字段变更后由自动化传播”，并让错误能够沿着字段和 PR 记录回溯。