wholetrans/docs-matrix-spec
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity

Update translations

Browse source
This commit is contained in:
CDN 2025-04-20 16:13:37 +08:00
parent 4af1379d1e
commit 1030e735c0
Signed by: CDN
GPG key ID: 0C656827F9F80080
96 changed files with 13449 additions and 0 deletions
Download patch file Download diff file Expand all files Collapse all files

256
locales/zh-Hans/proposals.md Normal file
View file

@ -0,0 +1,256 @@
---
title: "规范变更提案"
weight: 60
type: docs
---
{{< boxes/warning >}}
本页面的翻译未经核对，可能存在翻译质量不佳、错翻、漏翻等情况。您可以在 <a href="https://codeberg.org/wholetrans/docs-matrix-spec">Forgejo 存储库</a> 打开 Issue、提交 Pull Request 或<a href="mailto:errata@wholetrans.org">邮件联系</a>我们提出改进建议和参与翻译与核对。
{{< /boxes/warning >}}
如果您有兴趣提交 Matrix 规范的变更，请注意以下指南。
大多数对规范的更改都需要正式的提案。漏洞修复、拼写错误，以及对现有行为的澄清不需要提案——详见[贡献指南](https://github.com/matrix-org/matrix-spec/blob/main/CONTRIBUTING.rst)以了解哪些需要、哪些不需要提案。
提案流程包括一定的技术写作，由所有人评审，通过后被接受，最终将您的想法作为已提交的更改实现到[规范仓库](https://github.com/matrix-org/matrix-spec)中。
欢迎认识[核心团队成员](https://matrix.org/foundation)，这是一个负责确保规范流程尽可能顺畅、顺利的专家小组。规范核心团队成员会尽力参与讨论，在讨论变得冗长时进行总结，并总体上推动所有人受益。团队成员可凭多数决定提案状态的变更，并且个人在提案讨论中拥有最终裁决权。
## 指导原则
提案**必须**着眼于整个 Matrix 生态系统的整体利益，而非仅惠及或优待某个单一参与者或部分参与者，并且不得包含任何受专利限制的知识产权。核心团队成员承诺以中立托管人的身份代表整个 Matrix 生态系统履行职责。
为澄清起见：Matrix 生态系统指任何使用 Matrix 协议的人。这包括客户端用户、服务器管理员、客户端开发者、机器人开发者、桥接与应用服务开发者、通过第三方网络间接使用 Matrix 的用户及管理员、服务器开发者、房间版主与管理员、基于 Matrix 构建产品或服务的公司/项目、规范贡献者、翻译人员以及最初的创造者等。
“整体利益”可以包括最大化：
- 可在开放 Matrix 网络上联系到的终端用户数量
- Matrix 网络上的活跃常用用户数量（例如：30 天留存的联合用户）
- 开放联合体中在线服务器的数量
- 构建于 Matrix 之上的开发者数量
- 使用 Matrix 的独立实现数量
- 可在开放 Matrix 网络上通过桥接可达的终端用户数量
- 开放 Matrix 网络内容的信噪比（即最小化垃圾信息）
- 用户根据自身意愿发现内容的能力（赋权用户选择看什么或不看什么）
- Matrix 规范的质量与实用性（以开发者实现兼容规范的客户端、服务器、机器人、桥接以及其他集成的难易程度和能力为定义，且无需参考任何其他外部资料）
此外，提案作者在对 Matrix 协议提出变更时应秉持以下价值观：
- 支持整个长期生态系统，而非单一利益相关方
- 开放而非专有锁定
- 互操作而非碎片化
- 跨平台而非特定平台
- 协作胜于竞争
- 易用胜于精英主义
- 透明胜于隐蔽
- 同理心胜于对立
- 实用主义胜于追求完美
- 证据胜于猜测
完整指导原则详情请参见 [MSC1779](https://github.com/matrix-org/matrix-spec-proposals/blob/main/proposals/1779-open-governance.md)。
## 技术说明
提案**必须**将 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](https://help.github.com/articles/basic-writing-and-formatting-syntax/) 编写首稿。
- 在文档中明确说明要解决的问题，以及拟议的多个解决方案及其权衡。
- 提案文档可由作者自定风格与内容，没有固定模板，目的是尽快迭代设计取得最佳方案。
- 但可参考[带建议标题模板](https://github.com/matrix-org/matrix-spec-proposals/blob/main/proposals/0000-proposal-template.md)入手。
- 谨慎撰写提案。明确指定所需更改，并论证其合理性。缺乏理由的变更很可能不会被社区接受。
- Fork 并向 [matrix-spec-proposals](https://github.com/matrix-org/matrix-spec-proposals) 仓库发起 PR。您的 PR ID 将作为 MSC ID 伴随该提案的整个生命周期。
- 文件必须放在 `proposals/` 目录下，文件名格式为 `1234-my-new-proposal.md`，其中 `1234` 为 MSC ID。
- PR 描述中必须包含渲染后的 Markdown 文档链接及提案摘要。
- 建议链接相关 MSC 或 [matrix-spec issues](https://github.com/matrix-org/matrix-spec/issues) 以提供上下文。
- 同时，请根据 [CONTRIBUTING.rst](https://github.com/matrix-org/matrix-spec/blob/main/CONTRIBUTING.rst) 要求为您的提案 PR 进行签名（sign off）。
- 广泛收集反馈。
- 目标是尽可能就最优解决方案达成最大共识。为此有时需权衡取舍。决策应覆盖所有主要用例。
- 针对特定提案征询意见的好渠道为 [\#matrix-spec:matrix.org](https://matrix.to/#/#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 评论中总结归档。
- 当核心团队成员认为讨论无新观点且有足够可行证据（见下文[实施提案](#implementing-a-proposal)），将提出进入最终评论期（FCP）的动议，并附带合并、关闭或延期的结论（*disposition*）。FCP 旨在为各方提供一小段时间，若有疑义可最终发声。在充分理由下，可取消 FCP。通常会先由一则评论综述当前讨论状态及理由。
- 规范核心团队成员可随时提出关切，阻止 FCP 启动。仅当 75% 的核心团队成员就 FCP 结论达成一致，且所有现有关切都已解决后，FCP 方能启动。
- FCP 将进行 5 天，为其他关心方留出答复时间。若有充分反对理由，核心团队成员可提出关切阻止 FCP 结束。此举不会重置/暂停 5 天计时，但在所有关切解决前 FCP 不会终结。如需大量调整 MSC 才能解决关切，FCP 可能被取消并重新申请。FCP 完成后，将执行其结论指令。
- 提案被接受合并后，需提交规范实际变更的 PR（spec PR）。但只有在给出实现证据**且**证明实践可行的情况下 spec PR 才能被采纳。PR 描述需附实现链接。若过程中发现与原方案有重大且意料之外的改变，则需额外提交 MSC。非根本性的小变更允许，但**必须**在原提案文档中注明。此举可避免日后查阅提案者以为旧信息已纳入规范。
- 规范 PR 亦需参照 [CONTRIBUTING.rst](https://github.com/matrix-org/matrix-spec/blob/main/CONTRIBUTING.rst) 进行签名。
- 您的 PR 将再次接受评审，若实现充分则有望合并。届时，恭喜您成功为 Matrix 协议、用户及开发者带来了贡献！
下列流程图以可视化形式说明了提案处理流程。注意，提案各阶段均通过 [matrix-spec-proposals](https://github.com/matrix-org/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](https://github.com/matrix-org/matrix-spec-proposals/issues?q=is:open+draft:true) | 尚在进行中的提案文档，公开征集反馈。标题请加 `[WIP]` 前缀，便于评审快速筛查。 |
| 提案评审中 | [无标签](https://github.com/matrix-org/matrix-spec-proposals/issues?q=draft:false+label%3Aproposal+-label%3Aabandoned+-label%3Afinal-comment-period+-label%3Afinished-final-comment-period+-label%3Amerged+-label%3Aobsolete+-label%3Aproposal-postponed+-label%3Aproposed-final-comment-period+-label%3Aproposal-in-review+-label%3Aspec-pr-in-review+-label%3Aspec-pr-missing) | 已准备好，等待核心团队与社区评审的提案。 |
| 已提议最终评论期 | [proposed-final-comment-period](https://github.com/matrix-org/matrix-spec-proposals/issues?q=draft:false+label%3Aproposal+label%3Aproposed-final-comment-period+) | 正在等待 75% 多数团队成员签批以进入最终评论期 |
| 最终评论期 | [final-comment-period](https://github.com/matrix-org/matrix-spec-proposals/issues?q=draft:false+label%3Aproposal+label%3Afinal-comment-period+) | 提案已进入最终评论期（合并、关闭或延期） |
| 完成最终评论期 | [finished-final-comment-period](https://github.com/matrix-org/matrix-spec-proposals/issues?q=draft:false+label%3Aproposal+label%3Afinished-final-comment-period+) | 最终评论期已结束，等待实现证明 |
| 规范 PR 待提交 | [spec-pr-missing](https://github.com/matrix-org/matrix-spec-proposals/issues?q=draft:false+label%3Aproposal+label%3Aspec-pr-missing) | 提案已达成一致并通过实现证明，待提交规范的 PR |
| 规范 PR 评审中 | [spec-pr-in-review](https://github.com/matrix-org/matrix-spec-proposals/issues?q=draft:false+label%3Aproposal+label%3Aspec-pr-in-review+) | 规范 PR 已提交，正在评审中 |
| 规范 PR 已合并 | [merged](https://github.com/matrix-org/matrix-spec-proposals/issues?q=draft:false+label%3Aproposal+label%3Amerged) | 已有充分可用实现并合并规范 PR 的提案 |
| 已延期 | [proposal-postponed](https://github.com/matrix-org/matrix-spec-proposals/issues?q=draft:false+label%3Aproposal+label%3Aproposal-postponed+) | 暂时被阻止或暂时无用、但未来或有价值的提案 |
| 已废弃 | [abandoned](https://github.com/matrix-org/matrix-spec-proposals/issues?q=draft:false+label%3Aproposal+label%3Aabandoned) | 作者/牧羊人无回复的提案 |
| 已过时 | [obsolete](https://github.com/matrix-org/matrix-spec-proposals/issues?q=draft:false+label%3Aproposal+label%3Aobsolete+) | 被其他提案或决策取代而失效的提案 |
## 分类
我们使用分类标签为 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](https://matrix.to/#/#matrix-spec:matrix.org) 咨询。提案可能需服务端与客户端共同实现。
尚未被实现的提案将被打上 `needs-implementation` 标签。实现后，请在 GitHub issue 评论告知。已实现但尚未审核的，将被打上 `implementation-needs-checking` 标签。
### MSC/创意早期发布
为便于软依赖正式规范发布的软件提前放行，要求实现采用如下方式，防止官方 Matrix 命名空间堆积开发/测试数据。
**注意：** 未发布的实现（包括用于证明 MSC 可行的概念验证）无需遵循本流程。
1. 有了新特性的想法。
1. 利用非稳定端点、厂商前缀及不稳定特性标志实现该特性。
- 使用非稳定端点时**必须**加厂商前缀。例如：`/_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 评审初期阶段，可能还得兼容早期方案版本。
- 若无法承担技术债务（或不可能保持前后兼容，比如不可回滚的用户认证变更），就不应尝试实现该特性，应耐心等待规范发布。
- 若早期发布后，方案出现向后不兼容的重大更动，特性标志也应更换，方便实现随时适配。
1. 实现前后/并行，按上文流程开放 MSC 并征求意见。
1. FCP 开启前，核心团队需有 MSC 按提案方式有效实现的证据。典型方法是有实现 PR，无须正式发布业可规避严重的前后兼容风险。
1. 完成 FCP 流程，如无异议 MSC 合并落地。
1. 各实现可切换到稳定前缀（如端点由 `/unstable/org.matrix.mscxxxx/frobnicate` 变为 `/v1/frobnicate`），前提要与早期实现兼容。如确实无法兼容且需新规范发布，则应维持用不稳定前缀。
1. 提交 PR 将更改纳入 Matrix 规范。
1. 规范发布。
1. 规范发布后立即起约 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](https://github.com/matrix-org/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 %}}