Orleans 仓库贡献工作流详解：AGENTS.md 中的包兼容性验证、生成 API 表面与文档样例治理

后端微服务【免费下载链接】orleansCloud Native application framework for .NET项目地址https://gitcode.com/gh_mirrors/or/orleans点击查看免费下载导读本文以 Orleans 仓库根目录的 AGENTS.md 为主线系统讲解维护者在提交代码时必须遵循的三套工程质量门禁分支与 PR 工作流、包兼容性验证Package Validation工作流、以及由 GenAPI 生成的公共 API 表面src/api再生成流程。同时结合 docs/AGENTS.md 与 samples/AGENTS.md 两套递归规则说明文档与示例代码如何被当作一等交付物进行治理。读完本文你将掌握如何在 Orleans 仓库中安全地引入破坏性 API 变更、如何生成并提交 API 表面文件、以及文档与样例贡献应满足的验证要求。一、文档定位一套递归生效的仓库工作流契约根目录 AGENTS.md 是 Orleans 仓库对人类或 AI贡献者的行为约束文件共 30 行分为三大主题Repository workflowPR 流程、Package compatibility包兼容性、Generated API surfaces生成 API 表面。它的覆盖范围是递归的——在 docs/AGENTS.md 和 samples/AGENTS.md 的开头都明确写着These rules apply recursively to ... The repository-level guidance also applies.即文档目录与样例目录在遵守自身规则之外还必须同时遵守根级工作流。与普通 CONTRIBUTING 文档不同这份文件规定的每一条都不是空泛约定而是与仓库中真实存在的构建产物和 CI 检查一一对应的CompatibilitySuppressions.xml、src/api/*.cs、gallery.json、Docs.slnx等下文将逐一给出证据。二、分支与 PR 工作流根文档对拉取请求的生命周期做了严格规定新 PR必须从dotnet/orleans上游仓库的main分支创建特性分支推送到经过认证的贡献者自己 fork 的仓库再向dotnet/orleans打开 PR。既有贡献者的 PR当维护者编辑权限开启且认证允许时可以直接向 PR 作者 fork 仓库中的 head 分支推送更新。每次推送前必须运行git remote -v按 URL 核实推送目标而不是依赖 remote 名称或硬编码的origin。红线绝不把特性分支推送到 URL 指向github.com/dotnet/orleans的 remote无论 HTTPS 还是 SSH若误推需立即删除该分支。rebase 纪律rebase PR 分支后只能使用--force-with-lease禁止使用--force以免覆盖他人推送的提交。提交信息提交与 PR 标题遵循 Conventional Commits 规范评审时发现不符合规范的 PR 标题应予以修正。评审要点评审变更时须检查/docs与/samples目录是否需要同步的文档或示例更新PR 描述应聚焦于问题、方案与理由不要包含测试命令段落。这套流程的核心意图是保证dotnet/orleans上游仓库的main分支永远只接收经由 fork 且经过核实的变更同时借助--force-with-lease防止协同推送时的历史覆盖风险。三、包兼容性验证破坏性 API 变更的完整流程这是根文档篇幅最大的主题也是 Orleans 作为发布 NuGet 包的开源框架最核心的工程质量关卡。仓库中所有可打包packable的源码项目都会用配置在 src/Directory.Build.props 中的已发布基线版本对自身产出的包做兼容性校验CompatibilityTargetFrameworksnetstandard2.0/CompatibilityTargetFrameworks DefaultTargetFrameworksnet8.0;net10.0/DefaultTargetFrameworks OrleansPackageValidationBaselineVersion10.3.1/OrleansPackageValidationBaselineVersion从源码可见当前基线版本为10.3.1文件注释明确写道Update this after each stable Orleans release and remove suppressions made obsolete by that baseline.每次稳定版发布后更新此值并清理因此过时的抑制项并指引查看 CONTRIBUTING.md 了解破坏性变更流程。3.1 CP* 与 PKV* 诊断的含义在 .NET 的 Package Validation 体系下CP*Compatibility与PKV*Package Validation开头的诊断 ID 分别对应 API 兼容性与包内容校验问题诊断 ID 的权威清单见 Microsoft 的 package-validation 文档。根文档明确要求CP*与PKV*失败是兼容性发现结果compatibility findings必须按真实问题处理不得当作可全局关闭的警告。禁止通过关闭包验证package validation或把CP*/PKV*加入NoWarn来解决兼容性失败。3.2 抑制文件 CompatibilitySuppressions.xml仓库中真实的抑制文件示例位于 src/Orleans.Journaling/CompatibilitySuppressions.xml。它的结构如下节选含net10.0与net8.0两组?xml version1.0 encodingutf-8? Suppressions xmlns:xsihttp://www.w3.org/2001/XMLSchema-instance xmlns:xsdhttp://www.w3.org/2001/XMLSchema Suppression DiagnosticIdCP0001/DiagnosticId TargetT:Orleans.Journaling.HostingExtensions/Target Leftlib/net10.0/Orleans.Journaling.dll/Left Rightlib/net10.0/Orleans.Journaling.dll/Right IsBaselineSuppressiontrue/IsBaselineSuppression /Suppression Suppression DiagnosticIdCP0002/DiagnosticId TargetM:Orleans.Journaling.DurableGrain.get_StateManager/Target Leftlib/net10.0/Orleans.Journaling.dll/Left Rightlib/net10.0/Orleans.Journaling.dll/Right IsBaselineSuppressiontrue/IsBaselineSuppression /Suppression /Suppressions从该文件可以看到实际使用的诊断类型CP0001类型级 API 差异如T:Orleans.Journaling.HostingExtensions、CP0002成员级 API 差异如M:Orleans.Journaling.DurableGrain.get_StateManager每个抑制条目都精确到Target目标符号、Left/Right对比的库资产并标记IsBaselineSuppression。这印证了根文档把抑制范围限定到受影响的包与 API的要求——抑制是逐符号的而不是整个包级别的开关。3.3 引入一次已批准破坏性变更的标准操作序列根文档给出了精确到命令行参数的流程这也是本文最值得照做的部分先触发失败当破坏性变更是有意为之intentional时先对受影响项目执行普通 Release 打包捕获兼容性失败dotnet pack project --configuration Release生成抑制文件通过设置GenerateCompatibilitySuppressionFile属性重新打包让工具自动生成抑制文件dotnet pack project --configuration Release /p:GenerateCompatibilitySuppressionFiletrue人工审阅检查项目旁生成的CompatibilitySuppressions.xml只保留描述已批准破坏的条目保持抑制范围限定在受影响的包和 API并把该文件随破坏性变更一起提交。回归验证去掉GenerateCompatibilitySuppressionFile再次执行普通 Release 打包要求必须通过。3.4 目标框架移除的特殊处理对于有意的目标框架移除target-framework removal根文档要求不要使用 API 抑制而是为具体包添加PackageValidationBaselineFrameworkToIgnore条目。这与 API 抑制的语义不同框架移除属于资产层面的变化用专用项来声明基线中的某个框架已被有意忽略从而避免用逐符号抑制去掩盖整体资产的消失。3.5 抑制文件的长期维护当包含该破坏性变更的版本发布、并成为新的配置基线后应重新生成或删除旧的抑制文件避免过时条目持续累积。这与 src/Directory.Build.props 注释中remove suppressions made obsolete by that baseline的要求相互印证形成一个破坏→抑制→发布→基线更新→清理抑制的闭环。四、生成 API 表面src/api 的再生成流程根文档规定src/api下的文件是生成的公共 API 表面generated public API surfaces禁止手工编辑。从目录结构看src/api/Orleans.Core/Orleans.Core.cs 这类每项目一文件的布局正是 GenAPI 为每个 packable 项目产出的参考程序集源码。4.1 何时需要再生成只要修改了某个 packable 源码项目的公共 API就必须使用与 CI 相同的 restore 配置和 GenAPI target 重新生成该项目的 API 文件。4.2 完整命令序列根文档给出了两步精确命令dotnet restore project --configfile .github/NuGet.GenAPI.Config -p:GenerateOrleansApiSourcetrue dotnet build project --framework net8.0 --configuration Release --no-incremental --no-restore -p:GenerateOrleansApiSourcetrue /t:Build;GenAPIGenerateReferenceAssemblySource4.3 底层机制从仓库源码可以印证这些命令的运作方式src/Directory.Build.props 第 64-66 行定义了GenerateOrleansApiSource属性与 GenAPI 包的绑定关系ItemGroup Condition$(GenerateOrleansApiSource) true PackageReference IncludeMicrosoft.DotNet.GenAPI.Task PrivateAssetsAll / /ItemGroup即只有设置了该属性MSBuild 才会引入Microsoft.DotNet.GenAPI.Task从而激活GenAPIGenerateReferenceAssemblySourcetarget。.github/NuGet.GenAPI.Config确认存在于 .github/NuGet.GenAPI.Config是专用的 NuGet 配置文件把 GenAPI 包映射到其公共传输源public transport feed而普通 restore 只使用仓库的 CFSClient-Side Feed源这正是命令中必须显式传入--configfile的原因。4.4 提交要求生成的src/api变更必须与实现变更一起评审并提交。也就是说改了公共 API 却忘记更新 src/api 在 Orleans 仓库会被视为不完整的 PR。五、docs/ 与 samples/ 的递归治理规则根文档还要求评审时检查/docs与/samples是否需要同步更新。而这两份子 AGENTS 文件各自定义了严格的贡献契约。5.1 文档目录docs/AGENTS.mddocs/AGENTS.md 对docs/下的文档、片段snippets与示例递归生效核心规则包括代码示例治理每个 C# 示例必须放在 snippets 项目中并用带名字的:::coderegion 引入禁止在 Markdown 中直接写行内 C# 代码块展示片段缺失上下文时可在 region 外添加隐藏声明示例必须自包含、可编译不得发布伪代码。文档与 snippet 项目目标框架为net10.0可在 docs/site/src/content/docs/Directory.Build.props 中看到集中声明。版本纪律所有Microsoft.Orleans.*包引用必须使用批准的10.2.2版本snippet 项目集中声明于 docs/site/src/content/docs/Directory.Build.props只有在窄化的迁移示例中才允许使用更旧的 Orleans 包且必须放在migration目录下、在OrleansDocumentationVersionException中说明理由不得用不含某 API 的旧包演示未发布 API。链接规范Orleans 文档链接使用相对链接以兼容https://dotnet.github.io/orleans外部文档链接必须完整限定且使用不含区域码的规范形式如https://learn.microsoft.com/azure/...不得给已迁移的.md后缀带入发布链接也不得对外部站点使用根相对路径。API 引用公共 .NET 符号用 DocFX xref 语法链接到生成的 API 文档如xref:Orleans.Runtime.IPersistentState1、xref:Orleans.Hosting.AzureTableSiloBuilderExtensions.AddAzureTableGrainStorage*?displayPropertynameWithType字面量、配置值、CLI 命令、文件名等非链接符号使用行内代码发布前须确认 xref 目标存在于生成的 API 表面中。文档类型分工文档被明确分为 Architecture/implementation detail、Cookbook/how-to、Walkthroughs/tutorials、Conceptual、API reference、FAQ/troubleshooting 六类强调各司其职、相互链接、不要混写。注册与生成物每个新页面必须登记到 docs/site/src/content/docs/toc.yml 对应文档类型分区禁止手工编辑生成的站点输出、生成的 API 数据、dist、node_modules、bin、obj及生成的.mdx兄弟文件。5.2 样例目录samples/AGENTS.mdsamples/AGENTS.md 对samples/下的一切递归生效核心规则包括编排方式优先用 .NET Aspire 编排样例依赖新写或多进程改造的样例、以及需要外部依赖存储、数据库、缓存的样例都应带 app host命名为Sample.AppHost、设置IsAspireHost、引用Aspire.AppHost.Sdk通过Aspire.Hosting.Orleans的builder.AddOrleans(default)WithClustering(...)、WithGrainStorage(...)接线服务项目加WithReference(orleans)。文档点名 samples/JournaledTodoList 为规范布局、samples/JournalingAzureBlobJson 为单服务示例。项目独立性每个样例项目目标net10.0且不可打包non-packable只能引用Microsoft.Orleans.*NuGet 包严禁项目引用src/——每个样例文件夹必须是能从仓库复制出去、原样独立编译的单元。版本管理机制samples/Directory.Packages.props 刻意不声明任何版本注释明确NuGet 只读取最近的 props缺自家文件的样例会在 restore 时失败每个样例自带Directory.Packages.props声明全部包版本PackageReference不得携带Version或VersionOverride。注册与生成物samples/Samples.slnx 必须恰好包含samples/下的全部项目并按样例分文件夹分组每个新样例要在 samples/gallery.json 中登记slug、title、description、path、sourceRepository、image、languages、tags、featured字段按此顺序samples/README.md 是生成文件改动gallery.json后运行pwsh ./samples/Update-Readme.ps1再生成严禁手改。六、验证门禁提交前的检查清单根文档与两份子文档共同要求构建样例不得需要云凭据只有运行样例才可能需要。具体的验证命令如下变更范围验证命令作用文档 snippet / snippet 项目策略docs/site/src/content/docs/validate-snippets.ps1构建普通 snippet 项目并对标记IsTestProjecttrue的项目运行行为级验证样例变更pwsh ./samples/Validate-Samples.ps1检查 gallery 清单、README 新鲜度、解决方案成员、包版本声明、样例自包含性并调用Build-Samples.ps1构建样例构建链路samples/Build-Samples.ps1先用唯一预发布版本打包Orleans.slnx再把这个版本与本地包源传给Samples.slnx确保样例验证的是当前源码产出的包而非项目引用文档站点在docs/site下运行npm run validate含重定向与渲染输出审计的链接、include、redirect、navigation、project-policy 检查聚合文档工程当存在docs/Docs.slnx时构建 docs/Docs.slnx 作为聚合文档工程提交前git diff --check检查空白错误其中 samples/Validate-Samples.ps1、samples/Build-Samples.ps1、samples/Update-Readme.ps1、docs/site/src/content/docs/validate-snippets.ps1 均为仓库中真实存在的脚本。文档站点本身还基于 Astro 构建docs/site/package.json支持本地渲染验证。七、总结把质量门禁落成可执行命令回顾根目录 AGENTS.md它的独特之处在于不空谈原则而是把每条质量要求绑定到具体的文件与命令破坏性变更dotnet pack触发失败 →GenerateCompatibilitySuppressionFiletrue生成抑制 → 人工审阅 CompatibilitySuppressions.xml → 普通打包回归通过公共 API 变更GenerateOrleansApiSourcetrue NuGet.GenAPI.Config 再生成 src/api 文件并随实现一起提交文档与样例 递归遵守 docs/AGENTS.md 与 samples/AGENTS.md并接受Validate-Samples.ps1、validate-snippets.ps1、npm run validate等脚本的机器校验。对希望在 Orleans 仓库或借鉴其工程实践的 .NET 项目中提交代码的开发者而言把这份工作流当成一份可执行清单来对待是避免 CI 返工、保证包与 API 长期稳定的最直接路径。赞分享后端微服务【免费下载链接】orleansCloud Native application framework for .NET项目地址https://gitcode.com/gh_mirrors/or/orleans点击查看免费下载相关推荐Orleans 仓库贡献完全指南环境搭建、构建验证、包兼容性检查与测试规范Orleans 仓库贡献完全指南环境搭建、构建验证、包兼容性检查与测试规范 本指南面向希望向 Orleans 开源仓库提交代码的开发者系统讲解从环境准备、克后端微服务Effect 库贡献开发指南基于 AGENTS.md 的编码规范、测试验证与文档工作流Effect 库贡献开发指南基于 AGENTS.md 的编码规范、测试验证与文档工作流 本指南围绕 Effect 官方仓库TypeScript 函数式编程与AI Agent代码智能体后端前端移动开发桌面应用Cloudflare Docs 仓库 AI Agent 协作指南AGENTS.md 中的仓库结构、内容约定与验证工作流Cloudflare Docs 仓库 AI Agent 协作指南AGENTS.md 中的仓库结构、内容约定与验证工作流 AGENTS.md 是 cloudfl文档创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考