NeverENG opened a new issue, #32: URL: https://github.com/apache/dubbo-net/issues/32
## 背景 目前 `README.md` 与 `readme_cn.md` 各约 900 行,混合了快速开始、配置、协议边界、排障和测试步骤。`Docs/` 有协议实现说明与导入历史记录,但缺少一条简洁的代码阅读路径。 本 Issue 承接 #16 的**第四组(双语文档)**,并调整其原有的“按使用手册章节扩展 `Docs/zh` / `Docs/en`”草案:这里不建设第二套覆盖代码的说明书,也不涉及 #16 的客户端职责与生命周期重构。用户使用手册将来如需迁移至网站,另行讨论;在有替代入口前不删减必要的现有说明。 ## 原则与职责边界 - **代码是行为的唯一事实源。** 文档不复制实现、默认值或测试结论来建立另一份可能过期的“事实”。需要说明行为时指向具体源码和测试;变更代码时核对受影响的文档链接与描述。 - **双语代码地图回答“从哪里读、为什么看”。** 英文与中文版本对应,按调用链呈现入口、关键步骤、上下文、模块职责、代码位置和相关测试;简述必要的交接点,不把代码逐行翻译成文档,也不为每个目录建一页。 - **RFC 记录架构思考与演进。** 只有真实的设计权衡才建 RFC;记录背景、约束、方案与取舍、决定、后果及状态,关联实施 PR/代码。RFC 解释“为什么”,不是当前运行行为的替代规范,也不是开发进度表。需要公开给两种语言读者的 RFC 保持双语对应。 - **Git/Issue/PR 是开发过程记录。** 拆分、推进顺序、讨论、验证和实际提交以可追溯的 Issue、PR、commit 为准;文档不维护重复的施工日志。 - **`CHANGELOG.md` 是索引。** 按版本或明确的阶段指向 Git tag/release、比较视图及相关 PR/commit;只给必要的用户可见摘要,不重写提交历史、RFC 或详细实施步骤。尚未发布的内容不得伪装成已发布版本。 - **历史与当前指南分开。** `Docs/ImportReviewStatus.md` 等导入记录可保留为历史材料,不放在日常代码阅读主路径。 ## 预期交付(分小 PR,范围以实际代码核对为准) 1. 盘点现有 README、协议文档、测试环境文档的主题与入口,确定保留、链接或归档的归属;不先批量搬文件。 2. 提供简洁、相互链接的中英文代码地图:从 `DubboClient` 进入注册发现、元数据、服务驱动、Native/Triple 执行器与对应测试;每个节点给出职责、调用关系和可点击的源码索引。README 保留最短示例与代码地图入口。 3. 约定 RFC 的编号、状态和最小双语模板;仅在出现具体架构决策时新增 RFC,不预造空目录或虚构决策。 4. 建立 `CHANGELOG.md` 的 Git 索引方式。已有历史按可核验的 tag、release、PR/commit 链接组织;没有发布依据的阶段明确标为未发布。 5. 在后续独立 PR 中按内容归属逐步精简 README;保留现有中英文入口、协议说明与测试环境说明的有效链接。 ## 验收条件 - 中英文入口与代码地图能互相导航;路径和调用链在当前 `main` 的源码与测试中可验证。 - 同一事实没有在 README、代码地图、RFC、Changelog 中各自维护不同版本;RFC 的决策背景与当前代码行为明确区分。 - `CHANGELOG.md` 的每项索引都指向真实、可核验的 Git 对象或 PR;不声称未发生的发布。 - 本地相对链接无失效;每个 PR 列明文档影响和验证结果。只改文档,不夹带运行时行为重构。 关联:#16(仅调整其文档工作线的方案;前三组仍由 #16 与相应子任务跟踪)。 -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected] --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
