Flutter 设计文档Design Doc规范指南从 Google Docs 模板、短链接到 GitHub 追踪 Issue 的完整流程【免费下载链接】flutterFlutter makes it easy and fast to build beautiful apps for mobile and beyond项目地址: https://gitcode.com/GitHub_Trending/flutter41/flutter本文为 Flutter 贡献者编写它基于仓库内的官方设计文档规范 docs/contributing/Design-Documents.md完整拆解了“写设计文档 → 创建短链接 → 建 GitHub 追踪 Issue → 多渠道征求反馈 → 将设计沉淀进 API 文档”的全流程并结合仓库中真实存在的 Issue 模板文件与示例源码帮助你掌握 Flutter 社区处理架构级讨论的正式方法。一、设计文档的定位引导讨论而非做决定在深入操作流程之前必须先理解 Flutter 项目对设计文档design doc的定位这决定了后文所有步骤的意义Flutter 项目把设计文档当作“引导讨论”的工具它的价值在于把问题背景、方案权衡集中呈现给社区从而激发高质量的讨论决定Decisions是在 PR 中做出的不在设计文档中做出批准Approvals也是在 PR 中给出的不在设计文档中给出。换言之设计文档是“讨论的载体”PR 才是“决策的落点”。这一原则在仓库其他贡献文档中也得到了呼应docs/contributing/Style-guide-for-Flutter-repo.md 的 “Get early feedback when designing new APIs” 一节明确建议设计新 API 或新功能时考虑先写一篇设计文档再向相关渠道征求反馈docs/contributing/Tree-hygiene.md 指出如果你的改动构成破坏性变更breaking change应认真考虑是否必要并“认真考虑写一篇设计文档”docs/contributing/issue_hygiene/README.md 解释了为什么大范围讨论不适合留在 Issue 里——GitHub 的评论缺乏线程化、通知容易被淹没因此更宏大的讨论更适合放到 Discord 或基于 Google Docs 的设计文档中进行讨论结束后再把结论摘要回写到 Issue。二、编写设计文档使用 Google Docs 与官方模板2.1 载体与模板规范推荐将设计文档写在Google Docs中并使用 Flutter 提供的官方模板模板短链接为flutter.dev/go/template模板内还描述了如何为你的设计文档铸造一个flutter.dev/go/foo形式的短链接。推荐使用官方模板有两个直接好处任何人看到文档格式都能立即识别这是一份 Flutter 设计文档能够明确传达该文档是公开共享的shared publicly。2.2 短链接Shortlink创建与测试模板会指导你创建形如flutter.dev/go/...的短链接例如为你的设计文档铸造flutter.dev/go/foo。规范特别强调发布短链接之前务必用无痕窗口incognito window实测该 URL 是否可访问这一步之所以关键是因为短链接一旦公开就会被 Issue、Discord、推文引用。如果文档的共享权限没配好别人打开链接看到“无权限访问”整个反馈收集流程就会卡死。2.3 共享设置让“任何人”可评论创建文档后必须配置Sharing 设置让所有人都拥有评论权限comment access。规范对这一点的解释很值得注意这样做的目的不一定是主动向整个社区征求反馈而是让分享“成为可能”——社区中任何人无论是否在你的雇主处工作、无论你是否已私下把文档分享给他都能把文档转给第三方而不需要你逐一点名授权。这是“公开可传播”与“主动群发”的区别。2.4 Google 员工Googlers的特殊要求规范中有一条硬性规定Google 员工创建设计文档必须使用非 corp非公司账号不能直接用工作邮箱创建。如果你不想用个人 GMail 账号可以获取fcontrib.org专用账号具体流程见 docs/contributing/Contributor-access.md 的 “fcontrib.org accounts” 一节在 Discord 的 #server-support 频道联系 Hixie 或其他 admin 申请由 admin 使用其 fcontrib 管理员凭据在 Google 管理后台创建账号并把生成的密码通过你的非 fcontrib 邮箱发送给你。三、创建 GitHub 追踪 Issue官方模板的字段解析设计文档创建完成后下一步是创建对应的 GitHub 追踪 Issue使用设计文档专用的 Issue 模板新建 Issue把自己设为 Issue 的 assignee给 Issue 添加design doc标签该标签会自动成为检索“所有设计文档”的统一入口——标签列表本身就是设计文档的索引在引入该标签之前还有一份历史设计文档归档可供追溯。在仓库中可以找到该模板的真实实现.github/ISSUE_TEMPLATE/07_design_doc.yml。从这个文件能确认模板的确切行为name: Share a Flutter design document description: As a contributor, I would like to share a design document. labels: [design doc] # 自动打上 design doc 标签 body: - type: markdown # 提示语请先遵循 Design-Documents.md 规范 - type: input id: document_link attributes: label: Document Link # 必填填入你的 flutter.dev/go 短链接 validations: required: true - type: textarea id: proposal_description attributes: label: What problem are you solving? # 必填简述你要解决的问题 validations: required: true从模板结构可以看出两点实操要点模板自动添加design doc标签labels: [design doc]你在填表时不需要再手动操作标签两个必填字段分别是“文档短链接”和“你在解决什么问题”——即每个设计文档 Issue 必须能回答What problem are you solving这与后文“好的反馈需要清晰的问题陈述”相互呼应。Issue 模板中还明确引用了本规范文档docs/contributing/Design-Documents.md作为行为依据可见 Issue 与文档是一一对应的追踪关系。四、征求反馈从 Issue 链接到 Dash Forum 的六级渠道规范按“你想要的反馈量级”给出了由近及远、逐级放大的反馈渠道反馈范围渠道说明已关注该议题的人对应 GitHub Issue如果该主题已有 Issue务必把设计文档链接贴到该 Issue 下——订阅了该 Issue 的人正是最关心进展的人这是最有效的触达方式团队内部Discord#hidden-chat只向团队成员征集反馈特定领域贡献者Discord#hackers-*系列频道想要对某个技术方向感兴趣的人的反馈所有 Flutter 贡献者Discord#hackers频道面向所有想参与 Flutter 开发的人更广泛的社区推文并请求团队成员转发、Reddit如 r/FlutterDev、Discord#announcements请求真的想要大量反馈时把链接发推文并告知团队成员以便转发或发布到跟随官方服务器的频道官方放大devrel 团队、UXR 团队、Dash Forum见下文三个“官方放大”渠道的具体操作Developer Relationsdevrel团队可请其广播“征求评论request for comments”请求。先在自己的 Discord 账号里询问无人响应时再在相应频道 ping HixieUX ResearchUXR团队可请研究者对提案做研究、用真实用户测试或在下一季度问卷中收集相关数据。同样先自行询问无人响应时再找 HixieDash Forum 会议如果你有 commit 权限可以请求在 Dash Forum 会议上讨论你的设计文档通常在美国西海岸时间周二上午 11 点举行。在 #hidden-chat 频道 ping Hixie 进入议程或使用该频道置顶的申请表单。各频道的完整背景可参考 docs/contributing/Chat.md。五、如何获得“好”的反馈六个常见原因与对策规范专门用一节分析“发出反馈征集却石沉大海”的原因这一部分对写好任何技术提案都有参考价值提案不清晰别人不知道该反馈什么。人们通常不愿提供宽泛的批评。自检清单问题陈述problem statement是否与方案solution分离是否有展示问题现状的示例代码是否有问题的截图或图示方案是否从第一性原理讲起读者并不天然拥有你的上下文缺少温和的导引他们会很快迷失。是否提供了拟议方案的示例代码还需要更多图或截图吗可以请一位你信任的人评估文档清晰度是否足够。提案太大没人能一下消化。能否拆分成更小的组件让每部分可以被独立理解最后再拼装成完整设计拆分可以都在同一篇文档内完成。别人不知道该针对什么给反馈。如果你对某个方面特别想听意见显式邀请针对该方面的反馈会非常有效。问错了人。对照上一节的渠道建议直接找受你提案影响的特定人群必要时逐级扩大范围直到拿到你期望数量的反馈。所有人都同意没人有话说。可以故意在提案中留一些“略显含糊intentionally sketchy”的细节来鼓励参与——规范诚实地标注了这是一个有风险的策略有时人们反而会“喜欢”你故意留的坏主意。提案太显然、太无趣。有些改动平淡到无争议诚实地说此时直接写 PR 并提交才是更好的选择——不必为设计文档而设计文档。六、设计文档的内容组织截图与图示工具规范给出了两类核心视觉素材的实操建议屏幕截图 / 录屏Screen captures在 macOS 上按CommandShift5可获得一整套截屏与录屏选项这是最便捷的获取方式图示Diagrams由于文字部分放在 Google Docs 中最便捷的方式就是使用 Google Docs 内置绘图选择InsertDrawingNew即可新建一张图。结合第五节的自检清单这些素材应当围绕两件事展开问题现状截图/图示、复现代码与方案架构图、示例代码。七、设计落地后把文档沉淀进源码 API 文档这是整份规范中最容易被忽视、却最关键的一条原则当你在实现某个设计时要在源码中详尽地记录它。API 文档通常是记录设计的标准位置。API 文档长到好几页、带各级小标题都是完全合理的。规范以 RenderBox 的文档作为正面范例。查看 packages/flutter/lib/src/rendering/box.dart 即可验证这一说法RenderBox类声明abstract class RenderBox extends RenderObject之前是长达数十行的类级文档注释内部以### Hit Testing、### Semantics、### Intrinsics and Baselines等小标题分节详细解释了命中测试协议、可访问性实现要求、固有尺寸与基线测量的四个方法computeMinIntrinsicWidth、computeMaxIntrinsicWidth、computeMinIntrinsicHeight、computeMaxIntrinsicHeight甚至提醒开发者在单测中把debugCheckIntrinsicSizes设为 true 来验证自己的覆写实现——这正是规范所说“多页、带小标题的 API 文档”的真实样貌。规范同时给出两条悲观但必要的假设不要假设讨论结束后还会有任何人去读你的设计文档不要假设会有人去看已关闭的 Issue 或 PR 讨论。结论只有一个设计的“最终版”必须存在于代码和 API 文档中那里才是长期可检索、随版本演进的记录。设计文档、Issue、PR 讨论三者都是过程性载体源码文档才是沉淀物。八、小结一张流程清单把上文串起来一份符合 Flutter 规范的完整设计文档工作流是用 Google Docs 官方模板写文档问题陈述与方案分离配示例代码、截图/图示配置共享权限为“任何人可评论”铸造flutter.dev/go/...短链接并用无痕窗口实测Google 员工使用非 corp 账号可用fcontrib.org账号见 Contributor-access.md用 07_design_doc.yml 模板建 GitHub Issue填入短链接与“你在解决什么问题”assign 给自己design doc标签由模板自动添加按量级选择反馈渠道Issue 链接 →#hidden-chat→#hackers-*→#hackers/#announcements→ 推文与 Reddit → devrel/UXR/Dash Forum收到反馈后回到文档迭代最终通过 PR 完成决策与批准实现落地时把设计以多页、带小标题的形式写进 API 文档如 RenderBox 的文档注释。延伸阅读docs/README.md 在文档总索引中列出了本规范Style-guide-for-Flutter-repo.md 补充了“从最贴近开发者的一层开始设计 API”等设计原则与新 API 设计文档的写作高度互补。【免费下载链接】flutterFlutter makes it easy and fast to build beautiful apps for mobile and beyond项目地址: https://gitcode.com/GitHub_Trending/flutter41/flutter创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考