wholetrans/docs-matrix-spec
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity
docs-matrix-spec/locales/zh-Hans/proposals.md
CDN 1030e735c0
Update translations
2025-04-20 16:13:37 +08:00

24 KiB
Raw Blame History

title weight type
规范变更提案 60 docs

{{< boxes/warning >}} 本页面的翻译未经核对，可能存在翻译质量不佳、错翻、漏翻等情况。您可以在 Forgejo 存储库 打开 Issue、提交 Pull Request 或邮件联系我们提出改进建议和参与翻译与核对。 {{< /boxes/warning >}}

如果您有兴趣提交 Matrix 规范的变更，请注意以下指南。

大多数对规范的更改都需要正式的提案。漏洞修复、拼写错误，以及对现有行为的澄清不需要提案——详见贡献指南以了解哪些需要、哪些不需要提案。

提案流程包括一定的技术写作，由所有人评审，通过后被接受，最终将您的想法作为已提交的更改实现到规范仓库中。

欢迎认识核心团队成员，这是一个负责确保规范流程尽可能顺畅、顺利的专家小组。规范核心团队成员会尽力参与讨论，在讨论变得冗长时进行总结，并总体上推动所有人受益。团队成员可凭多数决定提案状态的变更，并且个人在提案讨论中拥有最终裁决权。

指导原则

提案必须着眼于整个 Matrix 生态系统的整体利益，而非仅惠及或优待某个单一参与者或部分参与者，并且不得包含任何受专利限制的知识产权。核心团队成员承诺以中立托管人的身份代表整个 Matrix 生态系统履行职责。

为澄清起见：Matrix 生态系统指任何使用 Matrix 协议的人。这包括客户端用户、服务器管理员、客户端开发者、机器人开发者、桥接与应用服务开发者、通过第三方网络间接使用 Matrix 的用户及管理员、服务器开发者、房间版主与管理员、基于 Matrix 构建产品或服务的公司/项目、规范贡献者、翻译人员以及最初的创造者等。

“整体利益”可以包括最大化：

  • 可在开放 Matrix 网络上联系到的终端用户数量
  • Matrix 网络上的活跃常用用户数量（例如：30 天留存的联合用户）
  • 开放联合体中在线服务器的数量
  • 构建于 Matrix 之上的开发者数量
  • 使用 Matrix 的独立实现数量
  • 可在开放 Matrix 网络上通过桥接可达的终端用户数量
  • 开放 Matrix 网络内容的信噪比（即最小化垃圾信息）
  • 用户根据自身意愿发现内容的能力（赋权用户选择看什么或不看什么）
  • Matrix 规范的质量与实用性（以开发者实现兼容规范的客户端、服务器、机器人、桥接以及其他集成的难易程度和能力为定义，且无需参考任何其他外部资料）

此外，提案作者在对 Matrix 协议提出变更时应秉持以下价值观：

  • 支持整个长期生态系统，而非单一利益相关方
  • 开放而非专有锁定
  • 互操作而非碎片化
  • 跨平台而非特定平台
  • 协作胜于竞争
  • 易用胜于精英主义
  • 透明胜于隐蔽
  • 同理心胜于对立
  • 实用主义胜于追求完美
  • 证据胜于猜测

完整指导原则详情请参见 MSC1779。

技术说明

提案必须将 Matrix 发展为分层协议：新特性应建立在共享抽象层之上，而非在协议栈中引入紧密垂直耦合。这样可以确保新功能能够在既有层之上快速演进，替换旧特性也不会影响协议栈中其他组件，也无需整个生态大规模升级。这对于 Matrix 作为联盟协议来说，能迅速演进并有效与中心化系统竞争至关重要。

例如，新特性应尽可能在最高抽象层实现（比如新事件类型，可叠加在现有房间语义之上，甚至无需 API 变更）。如果做不到，则退而求其次，对下层做向后兼容的更改（如房间 API）；再不行则考虑事件或 DAG 格式的更改等。不依赖现有规范基础设施、反而创建新原语或低层 API 的特性是极少见的。

向后兼容对 Matrix 至关重要，但不能以牺牲协议进化为代价。当没有其他方案时，允许对端点作不兼容更改，且必须以 API 新主版本进行版本管理。当没有其他方案时，对房间算法的不兼容更改也允许，且必须以房间算法新版本进行。

有时，对于高级功能应纳入哪个层级会有疑问：比如视频会议应在规范中正式定义，还是通过小组件（widget）实现？声誉系统是否应被规范？搜索引擎行为应被规范吗？

此类问题没有统一答案，但可遵循以下指导：

  1. 如果该功能对整个 Matrix 生态有益且符合上述指导原则，应由规范支持。
  2. 如果无需更改任何实现与规范即已可实现该功能，则不必加入规范中。
  3. 但如果最佳用户体验确实需要自定义实现行为，则应在规范中定义，使所有实现均可采纳。
  4. 规范绝不能依赖未规范/未标准化的第三方行为。

举例说明：

  1. 视频会议显然对整体生态有益，因此规范应支持其实现方式。
  2. 利用小组件可实现视频会议，无需客户端与服务器强制变更，因此可以不纳入规范。
  3. 若本地集成 Jitsi 客户端体验更佳……
  4. ……但这将依赖未规范、未标准化的第三方行为，因此不能加入规范。

故视频会议案例下，具体选择要么为 WebRTC 的 SFU 会议语义制定规范（或引用已有规范），要么仍采用基于小组件的方案（可选配 widget 扩展以更深集成视频会议场景）。

另一个例子：“如何在 Matrix 内可视化核磁共振成像（MRI）数据”几乎不会被收纳进 Matrix 规范（顶多成为扩展事件类型注册表中的自定义事件），因为现有文件传输和可扩展事件（MSC1767）等基础已为传输和可视化任意富数据提供了优秀工具。

支持公共搜索引擎大概率无需自定义规范特性（顶多需批量接口优化），它们可作为客户端使用现有 CS API。例外的情形是去中心化搜索架构确实需新 API 功能（避免中心化搜索引擎权力过度集中）。

诸如回复、线程消息、可编辑消息、垃圾/滥用/内容过滤（及声誉系统）这类功能，对整个 Matrix 生态确有益处，目前规范下无法互操作实现，因此必须引入规范更改。

流程

Matrix 规范变更提案（MSC）的具体提交流程如下：

  • 用 GitHub-flavored Markdown 编写首稿。
    • 在文档中明确说明要解决的问题，以及拟议的多个解决方案及其权衡。
    • 提案文档可由作者自定风格与内容，没有固定模板，目的是尽快迭代设计取得最佳方案。
    • 但可参考带建议标题模板入手。
    • 谨慎撰写提案。明确指定所需更改，并论证其合理性。缺乏理由的变更很可能不会被社区接受。
  • Fork 并向 matrix-spec-proposals 仓库发起 PR。您的 PR ID 将作为 MSC ID 伴随该提案的整个生命周期。
    • 文件必须放在 proposals/ 目录下，文件名格式为 1234-my-new-proposal.md，其中 1234 为 MSC ID。
    • PR 描述中必须包含渲染后的 Markdown 文档链接及提案摘要。
    • 建议链接相关 MSC 或 matrix-spec issues 以提供上下文。
    • 同时，请根据 CONTRIBUTING.rst 要求为您的提案 PR 进行签名（sign off）。
  • 广泛收集反馈。
    • 目标是尽可能就最优解决方案达成最大共识。为此有时需权衡取舍。决策应覆盖所有主要用例。
    • 针对特定提案征询意见的好渠道为 #matrix-spec:matrix.org。若需，可建立另一个房间并在 #matrix-spec:matrix.org 宣传。在 PR 描述中也应同步列出讨论房间。
    • 其他讨论区域包括：#matrix-dev:matrix.org（面向使用既有 Matrix API 的开发者），#matrix:matrix.org（面向运行 Matrix 应用/服务端的用户），以及 #matrix-architecture:matrix.org（Matrix 架构设计横向讨论）。
    • 规范提案流程以协作为宗旨，而非竞争，目标乃以最优权衡解决相关问题。作者应中立收集各方观点并寻求共识，但这有时耗时（或有作者偏见），此时可指定不偏不倚的“牧羊人（shepherd）”协助推进。牧羊人通常是规范核心团队中立成员或有经验的社区成员，不设正式指派流程。只需提出请求，即会根据空余分配。拥有牧羊人并非被采纳提案的必要条件。
  • 规范核心团队及社区将在 GitHub PR 评论区和 Matrix 相关房间共同评审、讨论。GitHub 之外的讨论应在 PR 评论中总结归档。
  • 当核心团队成员认为讨论无新观点且有足够可行证据（见下文实施提案），将提出进入最终评论期（FCP）的动议，并附带合并、关闭或延期的结论（disposition）。FCP 旨在为各方提供一小段时间，若有疑义可最终发声。在充分理由下，可取消 FCP。通常会先由一则评论综述当前讨论状态及理由。
  • 规范核心团队成员可随时提出关切，阻止 FCP 启动。仅当 75% 的核心团队成员就 FCP 结论达成一致，且所有现有关切都已解决后，FCP 方能启动。
  • FCP 将进行 5 天，为其他关心方留出答复时间。若有充分反对理由，核心团队成员可提出关切阻止 FCP 结束。此举不会重置/暂停 5 天计时，但在所有关切解决前 FCP 不会终结。如需大量调整 MSC 才能解决关切，FCP 可能被取消并重新申请。FCP 完成后，将执行其结论指令。
  • 提案被接受合并后，需提交规范实际变更的 PR（spec PR）。但只有在给出实现证据且证明实践可行的情况下 spec PR 才能被采纳。PR 描述需附实现链接。若过程中发现与原方案有重大且意料之外的改变，则需额外提交 MSC。非根本性的小变更允许，但必须在原提案文档中注明。此举可避免日后查阅提案者以为旧信息已纳入规范。
  • 您的 PR 将再次接受评审，若实现充分则有望合并。届时，恭喜您成功为 Matrix 协议、用户及开发者带来了贡献！

下列流程图以可视化形式说明了提案处理流程。注意，提案各阶段均通过 matrix-spec-proposals 拉取请求跟踪器上的对应标签追踪状态。

                           +                          +
         Proposals         |          Spec PRs        |  Additional States
         +-------+         |          +------+        |  +---------------+
                           |                          |
 +----------------------+  |         +---------+      |    +-----------+
 |                      |  |         |         |      |    |           |
 |      Proposal        |  |  +------= Spec PR |      |    | Postponed |
 | Drafting and Initial |  |  |      | Missing |      |    |           |
 |  Feedback Gathering  |  |  |      |         |      |    +-----------+
 |                      |  |  |      +----+----+      |
 +----------+-----------+  |  |           |           |    +----------+
            |              |  |           v           |    |          |
            v              |  |  +-----------------+  |    |  Closed  |
  +-------------------+    |  |  |                 |  |    |          |
  |                   |    |  |  | Spec PR Created |  |    +----------+
  |    Proposal PR    |    |  |  |  and In Review  |  |
  |     In Review     |    |  |  |                 |  |
  |                   |    |  |  +--------+--------+  |
  +---------+---------+    |  |           |           |
            |              |  |           v           |
            v              |  |     +-----------+     |
 +----------------------+  |  |     |           |     |
 |                      |  |  |     |  Spec PR  |     |
 |    Proposed Final    |  |  |     |  Merged!  |     |
 |    Comment Period    |  |  |     |           |     |
 |                      |  |  |     +-----------+     |
 +----------+-----------+  |  |                       |
            |              |  |                       |
            v              |  |                       |
 +----------------------+  |  |                       |
 |                      |  |  |                       |
 | Final Comment Period |  |  |                       |
 |                      |  |  |                       |
 +----------+-----------+  |  |                       |
            |              |  |                       |
            v              |  |                       |
 +----------------------+  |  |                       |
 |                      |  |  |                       |
 | Final Comment Period |  |  |                       |
 |       Complete       |  |  |                       |
 |                      |  |  |                       |
 +----------+-----------+  |  |                       |
            |              |  |                       |
            +-----------------+                       |
                           |                          |
                           +                          +

生命周期状态

注意： 所有标签都应加至提案 PR 上。

名称 GitHub 标签 描述
提案撰写与反馈 Draft pull request 尚在进行中的提案文档，公开征集反馈。标题请加 [WIP] 前缀，便于评审快速筛查。
提案评审中 无标签 已准备好，等待核心团队与社区评审的提案。
已提议最终评论期 proposed-final-comment-period 正在等待 75% 多数团队成员签批以进入最终评论期
最终评论期 final-comment-period 提案已进入最终评论期（合并、关闭或延期）
完成最终评论期 finished-final-comment-period 最终评论期已结束，等待实现证明
规范 PR 待提交 spec-pr-missing 提案已达成一致并通过实现证明，待提交规范的 PR
规范 PR 评审中 spec-pr-in-review 规范 PR 已提交，正在评审中
规范 PR 已合并 merged 已有充分可用实现并合并规范 PR 的提案
已延期 proposal-postponed 暂时被阻止或暂时无用、但未来或有价值的提案
已废弃 abandoned 作者/牧羊人无回复的提案
已过时 obsolete 被其他提案或决策取代而失效的提案

分类

我们使用分类标签为 MSC 归入工作流轨道。规范核心团队会根据被选工作重心优先处理对应分类的 MSC，并努力推动这些 MSC 提案流转。

当前分类如下：

名称 GitHub 标签 描述
核心 kind:core 协议成败关键特性。
功能 kind:feature 规范的可选新增功能。
维护 kind:maintenance 修正或澄清已存在规范内容。

核心 MSC 例如聚合、交叉签名、群组/社区等，这些若不实现，协议可能失效或沦为二流。功能类如增强媒体 API、新传输方式、收藏夹等，维护类如优化错误码、澄清 API 要求、为 API 添新属性提高易用性。

核心团队将根据以上描述为每个 MSC 分类。即使新 MSC 归入暂未聚焦领域，随着重点演变，也可随时调整。我们仍鼓励开放新 MSC，即使暂非当前焦点，也可推进甚至无需核心团队专注即合并。

实施提案

作为提案流程一环，规范核心团队要求有 MSC 实现的证据，方可进入 FCP。这通常是相应实现的分支/PR，证明 MSC 可以在实践中运行，有时 MSC 本身足够小，不需实现即可视为已证明。实现无需合并发布，但须展示 MSC 确实切实可行。若不确定是否需实现证明，请在 #matrix-spec:matrix.org 咨询。提案可能需服务端与客户端共同实现。

尚未被实现的提案将被打上 needs-implementation 标签。实现后，请在 GitHub issue 评论告知。已实现但尚未审核的，将被打上 implementation-needs-checking 标签。

MSC/创意早期发布

为便于软依赖正式规范发布的软件提前放行，要求实现采用如下方式，防止官方 Matrix 命名空间堆积开发/测试数据。

注意： 未发布的实现（包括用于证明 MSC 可行的概念验证）无需遵循本流程。

  1. 有了新特性的想法。
  2. 利用非稳定端点、厂商前缀及不稳定特性标志实现该特性。
    • 使用非稳定端点时必须加厂商前缀。例如：/_matrix/client/unstable/com.example/login。Matrix 中厂商前缀始终采用 Java 包命名规范。MSC 应明确早期采用者选用哪个前缀。
    • 注意不稳定命名空间不会自动继承稳定命名空间下的端点：例如，/_matrix/client/r0/sync 存在，不意味着 /_matrix/client/unstable/com.example/sync 也存在。
    • 若客户端需确认服务器支持此特性，需使用厂商前缀的不稳定特性标志。该标志会显示在 /versions 的 unstable_features 区段中，如 com.example.new_login。MSC 应说明首选使用哪个特性标志。
    • 正确采用该方法时，实现可随时发布此特性，前提是可接受相应的技术债务，即须确保足够的前后兼容。该实现必须支持该标志/服务器端实现消失，并对用户一般安全可靠。需注意，如果处于 MSC 评审初期阶段，可能还得兼容早期方案版本。
    • 若无法承担技术债务（或不可能保持前后兼容，比如不可回滚的用户认证变更），就不应尝试实现该特性，应耐心等待规范发布。
    • 若早期发布后，方案出现向后不兼容的重大更动，特性标志也应更换，方便实现随时适配。
  3. 实现前后/并行，按上文流程开放 MSC 并征求意见。
  4. FCP 开启前，核心团队需有 MSC 按提案方式有效实现的证据。典型方法是有实现 PR，无须正式发布业可规避严重的前后兼容风险。
  5. 完成 FCP 流程，如无异议 MSC 合并落地。
  6. 各实现可切换到稳定前缀（如端点由 /unstable/org.matrix.mscxxxx/frobnicate 变为 /v1/frobnicate），前提要与早期实现兼容。如确实无法兼容且需新规范发布，则应维持用不稳定前缀。
  7. 提交 PR 将更改纳入 Matrix 规范。
  8. 规范发布。
  9. 规范发布后立即起约 2 个月过渡期，期间实现鼓励彼此迁移至稳定端点。例如，服务器端可在规范发布后两个月后敦促客户端切换到稳定端点，反之亦然，若因服务器未支持新规范客户端尚未切换稳定前缀，则应适当反馈上游引起重视。

{{% boxes/note %}} MSC 仍必须描述稳定端点/特性的形式，并在末尾注明不稳定特性标志/前缀。例如，MSC 应提议 /_matrix/client/r0/new/endpoint，而非 /_matrix/client/unstable/com.example/new/endpoint。 {{% /boxes/note %}}

总结：

  • 在 MSC 完成 FCP 之前，实现不得使用稳定端点。完成后可使用，非强制。
  • 实现可在 MSC 合并进规范前即以默认方式提供用户可见的特性，前提需遵循上述流程。
  • 实现应警惕抢先于规范部署所产生的技术债务。
  • 厂商前缀由特性开发者自选，应使用 Java 包命名风格。基金会首选厂商前缀为 org.matrix。
  • 厂商前缀、不稳定标志、不稳定端点均应纳入 MSC，MSC 内容必须以提议稳定端点为主。一般末尾表格对照稳定及不稳定值。

提案跟踪

本页为依据 matrix-spec-proposals 仓库 issue 与 pull request 跟踪器中的提案列表动态生成的文档。

我们利用 MSC PR 描述中的标签与部分元数据生成本页面。标签由规范核心团队在分拣提案时根据仓库既有标签进行分配。

需额外说明，先前 MSC 流程中曾混用 GitHub issue 与 PR，导致部分 MSC 号取自 issue ID。GitHub 的一项有益特性是，在拉取 URL 中放入 issue ID 时能自动跳转对应 issue。因此，https://github.com/matrix-org/matrix-spec-proposals/pull/$MSCID 无论始于 issue 还是 PR，均可正确跳转至对应 MSC。

其他元数据：

  • MSC 号取自 GitHub Pull Request ID，贯穿提案全生命周期。该 ID 不一定代表时序先后。
  • GitHub PR 标题即为 MSC 标题。
  • 若有规范 PR，请在 issue 描述添加 "PRs: #1234" 字样链接规范 pr。
  • 创建日期取自 GitHub PR，可通过在 PR 描述增加 "Date: yyyy-mm-dd" 字样覆盖。
  • 更新时间取自 GitHub。
  • 作者为提案 PR 创建人，可在 issue 描述正文以 "Author: @用户名" 指定。请确保 @用户名 为 GitHub 用户名（必须含 @）。
  • 可通过在 issue 描述添加 "Shepherd: @用户名" 指定牧羊人，同样需为真实 GitHub 用户。

{{% proposal-tables %}}