尧图网站建设 
如何按 ASP.NET Core API Review 流程提交公共 API 变更并获得批准【免费下载链接】aspnetcoreASP.NET Core is a cross-platform .NET framework for building modern cloud-based web applications on Windows, Mac, or Linux.项目地址: https://gitcode.com/GitHub_Trending/as/aspnetcore如果你在 aspnetcore 仓库中实现的功能需要新增或修改公共 API实现代码本身并不能替你走完流程仓库要求把 API 变更单独提交为一个 API proposal issue经过dotnet/aspnet-api-review团队的评审拿到api-approved标签后这个 API 才能进入 RTM 发布。本文按仓库文档 docs/APIReviewProcess.md 和api-review技能 描述的路径说明从识别 API 变更到拿到批准的完整操作顺序。流程全景两个 issue一条主线整个流程在 docs/APIReviewProcess.md 中用 mermaid 流程图描述核心节点依次是识别出工作项需要 API 变更或新增可以开始实现并打开实现 PR使用api-review技能单独提交一个 API proposal issue给 proposal 打api-ready-for-review标签并通知评审团队在周会中评审未通过则回到 proposal 修改通过后加api-approved标签校验api-approved标签覆盖的是最终实现形态API 才能进入 RTM 发布。文档同时明确了一个关键边界实现可以先于评审完成。贡献者可以先把 API 实现出来、把 PR 标记为 ready 甚至合并之后 proposal 才拿到api-approvedPR 的 ready 与合并并不以api-approved为前置条件.github/skills/api-review/SKILL.md 的 Rules 一节同样重申了这一点。但反过来API 进入 RTM 发布前必须有api-approved。准备条件开始操作前按 SKILL.md 的 Inputs 一节你需要备齐两样东西Originating issue触发这次 API 变更的 issue 或功能请求包括其全部评论实现 PR 或 commits拟议的实现及其公共 API 变更尤其是PublicAPI.Unshipped.txt中的改动。注意文档中的一个限定PublicAPI.Unshipped.txt只追踪兼容性基线它不构成 API 批准。也就是说光在 PR 里改了PublicAPI.Unshipped.txt并不等于走完了 API Review。第一步用 api-review 技能创建 proposal issue打开实现 PR 后使用仓库内置的api-review技能.github/skills/api-review/SKILL.md从 originating issue 和实现 PR 生成 proposal issue。技能定义的 Workflow 是收集证据通读 originating issue 及全部评论检查实现 PR、commits 与 diff确认每一个被修改的 public/protected 类型、成员、签名、默认值或约定都有对应条目起草 proposal按 issue 正文模板 填写各节填写标准见 section guidelines附上来源依据在 issue 正文末尾把每个实质性论断映射回 originating issue 或实现变更中的原文引用格式为CONTENT: QUOTE FROM SOURCE自查草稿检查单在下一步列出单独提交 issue在dotnet/aspnetcore中创建要求如下——标题以[API Proposal]为前缀附完整正文打上api-suggestion和api-proposal两个标签issue 类型选Feature如可用回链 PR把 API proposal issue 的链接加到实现 PR 中且不要移除 PR 原有描述。仓库本身也提供了手动路径issue 模板 30_api_proposal.md 已预置api-suggestion、api-proposal标签和Feature类型可直接按它手工填写。无论用哪种方式proposal issue必须链接到 originating issue 和实现 PRdocs/APIReviewProcess.md 第 3 步的要求。第二步写一个合格的 proposal 正文模板包含五个章节其中前三个必填后两个可选章节是否必填内容要求Background and Motivation必填说明新 API 的目的与价值、当前局限并链接 originating issue 与实现 PR聚焦为什么需要而非实现细节Usage Examples必填展示 API 如何被消费用正确标注语言标识的代码块必要时覆盖同步/异步两种用法Proposed API必填完整的公共 API 签名 diff使用 ref-assembly 格式Alternative Designs可选考虑过的其他 API 形态及取舍确认没有时才写N/ARisks可选破坏性变更、性能回退、安全隐患等确认没有时才写N/AProposed API 一节是评审讨论的核心section guidelines 给出了硬性格式要求使用 ref-assembly 格式只有签名没有方法体包含完整的 namespace 与类型声明新增成员前缀删除前缀-列出所有重载与扩展方法向已有接口添加成员时展示完整类型层级可以基于PublicAPI.Unshipped.txt的变更但要重构成完整的 ref-assembly 声明而不是粘贴孤立的基线条目对不产出 ref assembly 的区域手写等价的 ref-assembly 形态。模板里给出的示例文档示例namespace Microsoft.AspNetCore.Http; public static class HttpResponseWritingExtensions { public Task WriteAsync(this HttpResponse response, StringBuilder builder); }Background and Motivation 的写法上docs/APIReviewProcess.md 给了一对对照均为文档示例Good: This is the API for the widget factory, users use it in startup code to configure how their widgets work. We have an overload that accepts URI, but not one that accepts string, so were adding it for convenience. Bad: Adding a string overload for Widget.ConfigureFactory.原则是让不在这个功能领域的评审者也能理解这个变更在做什么。变更越大需要的解释和上下文越多。第三步标记 ready-for-review 并进入评审提交 proposal 后当你认为它已经成型做两件事docs/APIReviewProcess.md 第 4 步给 issue 打上api-ready-for-review标签通知dotnet/aspnet-api-review团队。打标签前文档要求 issue 满足ready-for-review的两个条件有一段简短描述帮助不熟悉该领域的评审者理解背景API 变更以 ref-assembly 格式呈现。链接到 PR 中生成的 ref-assembly 代码即可若该区域不产出 ref assembly则手写等价的 ref-assembly 形态。aspnet-api-review团队每周召开一次 API Review 会议你的 proposal 会在下一次会议上被评审你必须有一位代表出席会议并且每次会议应包含该 API 变更相关区域 owner 的强制参与。如果 proposal 较大、需要提前讨论把上下文写在 issue 里可以让团队在会前就展开讨论。对于较小的评审文档还给了一个快捷分支直接 ping API 评审团队以对话形式快速完成评审而不必走周会。第四步获得批准并守住最终形态proposal 通过后给 issue 加上api-approved标签。流程并未到此结束docs/APIReviewProcess.md 第 7、8 步给出了批准后的责任issue owner 负责确保api-approved标签覆盖的是最终实现的 API 形态这是 API 进入 RTM 发布前的硬条件如果实现过程中修改了已提案或已批准的 API 形态必须更新 proposal 并把修订后的形态重新提交 API 评审之后再谈进入 RTM。对应的成功判定就是流程图中verify节点的检查验证 proposal issue 带有api-approved标签且其内容与最终实现一致。.github/skills/api-review/SKILL.md 的 Completion 一节也定义了操作层面的完成条件存在一个独立的 API proposal issue具备要求的标题前缀、完整正文、api-suggestion/api-proposal标签、originating issue 与实现 PR 的链接以及实现 PR 上的反向链接。评审时会被怎么衡量dotnet/aspnet-api-review团队评审时应用的约定仓库在 docs/APIReviewPrinciples.md 中维护但目前该文档仍只有占位条目Principle 1 / Convention 1且 review-public-api 技能 明确指出它 intentionally thin不应依赖它。实际的评审约定集中在这几处提交 proposal 前值得对照自查review-public-api 技能的 SKILL.md规则高亮包括命名Create*静态工厂、Try*可选查找、扩展方法名包含接收者、异步方法以Async结尾并携带最后的CancellationToken cancellationToken default参数、默认密封、Add*/Use*/Map*/With*方法族的固定契约、新重载优先于改签名等更详细的依据与类型/程序集放置规则见 references/conventions.md。这些约定同时说明了评审的典型结论形态Looks good as proposed、Changes recommended最常见通常是小幅形态修正或Recommend not adding例如改动已发布的默认行为属于破坏性变更、没有可证明的需求、或可以用用户侧扩展方法实现。限制与边界实现、PR 合并与 API 批准是解耦的PR 可以先合并但 API 进 RTM 前必须补齐api-approved评审可以发生在实现之前、期间或之后proposal 也可以在实现开始前就先提交Alternative Designs和Risks只有在确认没有相应内容时才写N/A技能规则要求先向用户问清再落N/A不能由工具凭空补写你是社区提交变更的 champion 时仓库文档的要求是像它本来就是你的变更一样准备参会能解释清楚为什么需要这个 API、为什么它是最好的形态。完成以上步骤后你的 API 变更就具备了进入 RTM 发布的条件形态再变化时回到更新 proposal 重新提交评审这一闭环即可。【免费下载链接】aspnetcoreASP.NET Core is a cross-platform .NET framework for building modern cloud-based web applications on Windows, Mac, or Linux.项目地址: https://gitcode.com/GitHub_Trending/as/aspnetcore创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 如何按 ASP.NET Core API Review 流程提交公共 API 变更并获得批准
如何按 ASP.NET Core API Review 流程提交公共 API 变更并获得批准【免费下载链接】aspnetcoreASP.NET Core is a cross-platform .NET framework for building modern cloud-based web applications on Windows, Mac, or Linux.项目地址: https://gitcode.com/GitHub_Trending/as/aspnetcore如果你在 aspnetcore 仓库中实现的功能需要新增或修改公共 API实现代码本身并不能替你走完流程仓库要求把 API 变更单独提交为一个 API proposal issue经过dotnet/aspnet-api-review团队的评审拿到api-approved标签后这个 API 才能进入 RTM 发布。本文按仓库文档 docs/APIReviewProcess.md 和api-review技能 描述的路径说明从识别 API 变更到拿到批准的完整操作顺序。流程全景两个 issue一条主线整个流程在 docs/APIReviewProcess.md 中用 mermaid 流程图描述核心节点依次是识别出工作项需要 API 变更或新增可以开始实现并打开实现 PR使用api-review技能单独提交一个 API proposal issue给 proposal 打api-ready-for-review标签并通知评审团队在周会中评审未通过则回到 proposal 修改通过后加api-approved标签校验api-approved标签覆盖的是最终实现形态API 才能进入 RTM 发布。文档同时明确了一个关键边界实现可以先于评审完成。贡献者可以先把 API 实现出来、把 PR 标记为 ready 甚至合并之后 proposal 才拿到api-approvedPR 的 ready 与合并并不以api-approved为前置条件.github/skills/api-review/SKILL.md 的 Rules 一节同样重申了这一点。但反过来API 进入 RTM 发布前必须有api-approved。准备条件开始操作前按 SKILL.md 的 Inputs 一节你需要备齐两样东西Originating issue触发这次 API 变更的 issue 或功能请求包括其全部评论实现 PR 或 commits拟议的实现及其公共 API 变更尤其是PublicAPI.Unshipped.txt中的改动。注意文档中的一个限定PublicAPI.Unshipped.txt只追踪兼容性基线它不构成 API 批准。也就是说光在 PR 里改了PublicAPI.Unshipped.txt并不等于走完了 API Review。第一步用 api-review 技能创建 proposal issue打开实现 PR 后使用仓库内置的api-review技能.github/skills/api-review/SKILL.md从 originating issue 和实现 PR 生成 proposal issue。技能定义的 Workflow 是收集证据通读 originating issue 及全部评论检查实现 PR、commits 与 diff确认每一个被修改的 public/protected 类型、成员、签名、默认值或约定都有对应条目起草 proposal按 issue 正文模板 填写各节填写标准见 section guidelines附上来源依据在 issue 正文末尾把每个实质性论断映射回 originating issue 或实现变更中的原文引用格式为CONTENT: QUOTE FROM SOURCE自查草稿检查单在下一步列出单独提交 issue在dotnet/aspnetcore中创建要求如下——标题以[API Proposal]为前缀附完整正文打上api-suggestion和api-proposal两个标签issue 类型选Feature如可用回链 PR把 API proposal issue 的链接加到实现 PR 中且不要移除 PR 原有描述。仓库本身也提供了手动路径issue 模板 30_api_proposal.md 已预置api-suggestion、api-proposal标签和Feature类型可直接按它手工填写。无论用哪种方式proposal issue必须链接到 originating issue 和实现 PRdocs/APIReviewProcess.md 第 3 步的要求。第二步写一个合格的 proposal 正文模板包含五个章节其中前三个必填后两个可选章节是否必填内容要求Background and Motivation必填说明新 API 的目的与价值、当前局限并链接 originating issue 与实现 PR聚焦为什么需要而非实现细节Usage Examples必填展示 API 如何被消费用正确标注语言标识的代码块必要时覆盖同步/异步两种用法Proposed API必填完整的公共 API 签名 diff使用 ref-assembly 格式Alternative Designs可选考虑过的其他 API 形态及取舍确认没有时才写N/ARisks可选破坏性变更、性能回退、安全隐患等确认没有时才写N/AProposed API 一节是评审讨论的核心section guidelines 给出了硬性格式要求使用 ref-assembly 格式只有签名没有方法体包含完整的 namespace 与类型声明新增成员前缀删除前缀-列出所有重载与扩展方法向已有接口添加成员时展示完整类型层级可以基于PublicAPI.Unshipped.txt的变更但要重构成完整的 ref-assembly 声明而不是粘贴孤立的基线条目对不产出 ref assembly 的区域手写等价的 ref-assembly 形态。模板里给出的示例文档示例namespace Microsoft.AspNetCore.Http; public static class HttpResponseWritingExtensions { public Task WriteAsync(this HttpResponse response, StringBuilder builder); }Background and Motivation 的写法上docs/APIReviewProcess.md 给了一对对照均为文档示例Good: This is the API for the widget factory, users use it in startup code to configure how their widgets work. We have an overload that accepts URI, but not one that accepts string, so were adding it for convenience. Bad: Adding a string overload for Widget.ConfigureFactory.原则是让不在这个功能领域的评审者也能理解这个变更在做什么。变更越大需要的解释和上下文越多。第三步标记 ready-for-review 并进入评审提交 proposal 后当你认为它已经成型做两件事docs/APIReviewProcess.md 第 4 步给 issue 打上api-ready-for-review标签通知dotnet/aspnet-api-review团队。打标签前文档要求 issue 满足ready-for-review的两个条件有一段简短描述帮助不熟悉该领域的评审者理解背景API 变更以 ref-assembly 格式呈现。链接到 PR 中生成的 ref-assembly 代码即可若该区域不产出 ref assembly则手写等价的 ref-assembly 形态。aspnet-api-review团队每周召开一次 API Review 会议你的 proposal 会在下一次会议上被评审你必须有一位代表出席会议并且每次会议应包含该 API 变更相关区域 owner 的强制参与。如果 proposal 较大、需要提前讨论把上下文写在 issue 里可以让团队在会前就展开讨论。对于较小的评审文档还给了一个快捷分支直接 ping API 评审团队以对话形式快速完成评审而不必走周会。第四步获得批准并守住最终形态proposal 通过后给 issue 加上api-approved标签。流程并未到此结束docs/APIReviewProcess.md 第 7、8 步给出了批准后的责任issue owner 负责确保api-approved标签覆盖的是最终实现的 API 形态这是 API 进入 RTM 发布前的硬条件如果实现过程中修改了已提案或已批准的 API 形态必须更新 proposal 并把修订后的形态重新提交 API 评审之后再谈进入 RTM。对应的成功判定就是流程图中verify节点的检查验证 proposal issue 带有api-approved标签且其内容与最终实现一致。.github/skills/api-review/SKILL.md 的 Completion 一节也定义了操作层面的完成条件存在一个独立的 API proposal issue具备要求的标题前缀、完整正文、api-suggestion/api-proposal标签、originating issue 与实现 PR 的链接以及实现 PR 上的反向链接。评审时会被怎么衡量dotnet/aspnet-api-review团队评审时应用的约定仓库在 docs/APIReviewPrinciples.md 中维护但目前该文档仍只有占位条目Principle 1 / Convention 1且 review-public-api 技能 明确指出它 intentionally thin不应依赖它。实际的评审约定集中在这几处提交 proposal 前值得对照自查review-public-api 技能的 SKILL.md规则高亮包括命名Create*静态工厂、Try*可选查找、扩展方法名包含接收者、异步方法以Async结尾并携带最后的CancellationToken cancellationToken default参数、默认密封、Add*/Use*/Map*/With*方法族的固定契约、新重载优先于改签名等更详细的依据与类型/程序集放置规则见 references/conventions.md。这些约定同时说明了评审的典型结论形态Looks good as proposed、Changes recommended最常见通常是小幅形态修正或Recommend not adding例如改动已发布的默认行为属于破坏性变更、没有可证明的需求、或可以用用户侧扩展方法实现。限制与边界实现、PR 合并与 API 批准是解耦的PR 可以先合并但 API 进 RTM 前必须补齐api-approved评审可以发生在实现之前、期间或之后proposal 也可以在实现开始前就先提交Alternative Designs和Risks只有在确认没有相应内容时才写N/A技能规则要求先向用户问清再落N/A不能由工具凭空补写你是社区提交变更的 champion 时仓库文档的要求是像它本来就是你的变更一样准备参会能解释清楚为什么需要这个 API、为什么它是最好的形态。完成以上步骤后你的 API 变更就具备了进入 RTM 发布的条件形态再变化时回到更新 proposal 重新提交评审这一闭环即可。【免费下载链接】aspnetcoreASP.NET Core is a cross-platform .NET framework for building modern cloud-based web applications on Windows, Mac, or Linux.项目地址: https://gitcode.com/GitHub_Trending/as/aspnetcore创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考