后端运维观测【免费下载链接】NLogNLog - Flexible and Structured Logging for various .NET Platforms项目地址https://gitcode.com/gh_mirrors/nl/NLog点击查看免费下载本文档是 NLog 开源仓库.NET 平台灵活的结构化日志框架中 CONTRIBUTING.md 的技术性解读与实战扩充。无论你是想报告 Bug、提交功能请求、提出问题还是准备向 NLog 提交 Pull Request本文都会结合仓库内的真实源码、构建脚本与测试工程逐步说明应该准备哪些信息、遵循哪些分支与代码规范、如何应对多 .NET 版本的条件编译以及如何在本地和云端完成构建验证。读完本文你将具备向 NLog 社区高效、合规地提交高质量贡献的完整能力。一、贡献前的角色定位NLog 团队为什么需要你NLog 核心团队规模较小无法独立修复每一个 Bug 或实现每一项特性因此社区贡献非常受欢迎。贡献的第一步不是急着写代码而是按照统一规范向 issue 列表 提交问题或功能请求让维护者能够快速复现、定位与评估。新手可以从标记为up-for-grabs的 issue 入手——这类任务通常范围明确、难度适中是熟悉 NLog 代码库与贡献流程的理想起点。在动手之前请先理解仓库的分支策略master分支仅接收纯粹的 Bug 修复面向 NLog 5.x 系列dev分支面向 NLog 6 的日常开发主线新功能、重构与大部分改动都应以它为基线。这一点在仓库的持续集成配置中得到印证appveyor.yml 中同时为master与dev分支配置了 NuGet 发布流程而 NLog.csproj 中AssemblyVersion为 6.0.0.0与dev 面向 NLog 6、master 面向 NLog 5.x的定位一致。二、Issue 报告规范三类请求各自要带什么无论哪一类请求请一律使用 fenced code blocks即 Markdown 的 代码块围栏包裹配置、代码与堆栈信息保证可读性与可复制性。1. 功能请求Feature requests提交新功能请求时至少提供以下信息当前的 NLog 版本目前已存在的临时 work-arounds绕过方案该功能实现后对应的配置示例使用 fenced code blocks。同时欢迎直接附带 Pull Request 与单元测试——功能请求如果自带可运行的实现与测试被采纳的概率会大大提高。2. 问题咨询Questions提问时请提供当前的 NLog 版本当前的配置XML 或代码形式使用 fenced code blocks如相关当前实际结果若包含异常请给出完整的异常细节如相关期望结果。当前结果 vs 期望结果的对比是维护者快速判断问题性质配置错误还是框架缺陷的关键信息。3. Bug 报告Bug reportsBug 报告是信息量要求最高的一类需要包含当前的 NLog 版本错误信息与堆栈跟踪使用 fenced code blocks内部日志Debug级别参见仓库中的内部日志实现与文档说明——InternalLogger.cs 提供了独立于常规日志管道的内部诊断输出可在排障时精确还原 NLog 自身的行为当前实际结果期望结果任何已尝试的 work-arounds当前的配置XML 或代码使用 fenced code blocks。同样地Bug 报告也欢迎附带 Pull Request 与单元测试。实践中能附带最小复现测试的 Bug 报告往往能以最快速度被确认和修复。三、代码提交规范文档注释与单元测试Pull Request 是 NLog 贡献的核心形式。仓库 CONTRIBUTING.md 对代码质量有两条硬性要求单元测试非常受欢迎新增功能或修复 Bug 时尽量同步补充/更新 tests/NLog.UnitTests 下的对应测试用例让改动可验证、可回归。公开 API 必须写文档注释任何 public 方法和属性都需要 XML 文档注释且要注释why为什么而不是how怎么做。最低要求如下方法Summary、param 和 return 三部分属性Summary 即可。这一规范并非停留在纸面——仓库通过 tools/CheckSourceCode 中的NLog.SourceCodeTests工程对源码做静态自检。SourceCodeTests.cs 会校验每个.cs文件的文件头版权声明、类名与文件名/命名空间的一致性在 appveyor.yml 中该检查被作为 CI 的固定步骤执行msbuild /t:rebuild后运行NLog.SourceCodeTests.exe no-interactive。因此贡献者在本地提交前就可以用同样的方式自检避免 CI 阶段返工。此外仓库还采用 T4 模板生成部分代码Logger-generated.tt、InternalLogger-generated.tt、AssemblyExtensionTypes.tt 分别生成对应的*-generated.cs。在 NLog.csproj 中可以看到这些.tt与生成的.cs的关联关系。若改动涉及这些模板需要同步在 Visual Studio 中重新运行模板生成并确认生成的代码与模板一致。四、多 .NET 版本与条件编译三大符号的使用要点NLog 是一个同时支持多种 .NET 平台的日志库。NLog.csproj 中默认构建的目标框架包括net35.NET Framework 3.5net46.NET Framework 4.6netstandard2.0netstandard2.1而项目描述进一步声明支持 .NET 6/7/8/9/10、.NET Standard 2.0/2.1、.NET Framework 3.5–4.8、Xamarin Android/iOS基于 .NET Standard以及 Mono 4。这意味着并非所有 API 在每个目标框架上都可用因此仓库约定使用以下条件编译符号#if NET35 #if NETFRAMEWORK #if NETSTANDARD2_1_OR_GREATER其中.NET Framework 如今才是异类新代码的默认预期是支持 NetStandard/NetCore因此重点是用NETFRAMEWORK来标记那些不适用于 NetStandard 或 NetCore 的代码路径。这些符号在源码中确实被大量使用。例如 AssemblyExtensionTypes.tt 生成的目标注册代码中EventLogTarget仅在#if NETFRAMEWORK下注册#if NETFRAMEWORK targetFactory.RegisterTypeNLog.Targets.EventLogTarget(EventLog, checkTypeExists); #endif同样地AppSettingLayoutRendererappsetting布局渲染器也只在#if NETFRAMEWORK下注册见 AssemblyExtensionTypes.tt。而在 ConversionHelpers.cs 等处则可以看到#if NETSTANDARD2_1_OR_GREATER || NET形式的组合用法说明较新的标准库 API 只在支持它们的框架上启用。NET35符号则用于标记 .NET Framework 3.5 时代缺失的新 API提供兼容实现。给贡献者的实操建议写新代码前先确认你的目标 API 在net35最老的基线上是否可用若 API 属于新平台优先用NETFRAMEWORK把老框架不支持的部分隔离出来而不是反过来为老框架写默认路径条件编译代码最好配有对应目标框架的单元测试仓库的 run-tests.ps1 中可以看到针对net35、net45、net462与net10.0的测试矩阵验证多框架行为是 CI 的常规动作。五、标准贡献流程Fork → 分支 → PRNLog 推荐的标准贡献流程如下ForkNLog 仓库到自己的账户从dev分支创建新分支关键 Bug 修复则从master创建用 Git 或 GitHub Desktop 检出代码提交 commit 并创建 Pull Request 到 NLog 仓库。再次强调分支对应关系Bug 修复应 targetingmaster分支其他改动 targetingdev分支NLog 6。错误地把新功能提交到master或把 5.x 的 Bug 修复提交到dev都可能被维护者要求重新基于正确分支。六、保持 Fork 与上游同步rebase 与 merge大部分情况下 Fork 与上游不同步并不是问题。但如果你希望把上游的改动同步回自己的仓库可以按以下方式操作。首次设置上游远程git remote add upstream https://github.com/NLog/NLog.git之后你的仓库将拥有两个 remote。更新 Fork 的标准流程是git fetch upstream git checkout your feature branch git rebase upstream/master ..fix if needed and git push -f如果rebase不顺利也可以改用git merge master作为替代方案。需要注意的是反向提交 PR从上游往 Fork 提 PR虽然可行但会污染 commit log因此不推荐。七、本地与云端构建Visual Studio 与 CI 配置1. 本地构建使用Visual Studio 2022打开解决方案 NLog.sln 即可构建。仓库中除核心库 src/NLog/NLog.csproj 外还包含多个扩展项目如 src/NLog.OutputDebugString、src/NLog.RegEx、src/NLog.Targets.AtomicFile、src/NLog.Targets.GZipFile、src/NLog.WindowsEventLog它们各有独立的README.md与测试工程。本地验证测试可参考 run-tests.ps1 中的脚本逻辑先dotnet restore再针对目标框架执行dotnet test。脚本还包含一个值得注意的细节——Windows 构建会用dotnet publish运行 tests/TestTrimPublish 来验证 AOT/Trim 兼容性并对src执行dotnet list package --vulnerable做依赖漏洞扫描。2. 云端 CIAppVeyor SonarQubeNLog 的云端构建与质量检查由以下工具承担AppVeyor负责 Windows 与 Linux 构建。仓库根目录的 appveyor.yml 配置了Visual Studio 2026与Ubuntu2204两个构建镜像矩阵master/dev分支构建成功后会发布 NuGet 包SonarQube负责代码覆盖率与静态质量分析。如果你想在自己的 Fork 上启用云端构建仓库根目录提供了完整的操作说明文档 howto-build-your-fork.md核心步骤只有三步用 GitHub 账号登录 AppVeyor → 在 projects 中选择你的 Fork 并点击 → 完成。所有配置都已经在appveyor.yml中无需额外修改。从 appveyor.yml 可以看到CI 在运行正式测试之前会依次执行源码合规检查NLog.SourceCodeTests.exe no-interactive与 XSD 校验脚本Test-XmlFile.ps1这意味着贡献者提交的代码不仅需要通过单元测试还需要通过文件头、类名命名、XSD 配置合法性等静态检查。八、扩展生态如何把新的 Target / Layout 加入官方列表NLog 提供了丰富的 Targets 与 Layouts 扩展生态。如果你的自定义 Target 或 Layout 希望被收录进官方配置列表可以按以下方式操作在 NLog 仓库为本体创建 Pull Request扩展组件本身的实现通常放在 src 下的独立扩展工程中如 src/NLog.RegEx、src/NLog.Targets.GZipFile在 NLog 的文档仓库中提交 Pull Request更新对应的配置文件NLog Targets→config/targets.jsonNLog Layouts→config/layouts.jsonNLog LayoutRenderers→config/layout-renderers.json在 NLog 核心库中扩展注册的底层机制是 AssemblyExtensionTypes.tt 这类 T4 模板生成代码运行时通过 ConfigurationItemFactory 把带TargetAttribute、LayoutAttribute、LayoutRendererAttribute、FilterAttribute、TimeSourceAttribute等特性的类型注册进配置工厂从而让 XML 配置中的名称如target xsi:type...能解析到对应实现。九、给贡献者的清单总结在提交 Pull Request 之前对照下面的清单做一次自检基于正确的分支创建功能分支Bug 修复 →master新功能 →dev已提供/更新对应模块的单元测试public 方法/属性已补齐 XML 文档注释方法Summary param return属性Summary多框架代码已正确使用NETFRAMEWORK、NETSTANDARD2_1_OR_GREATER、NET35条件编译符号若改动 T4 模板已同步重新生成对应的*-generated.cs本地已运行 run-tests.ps1 中对应的测试命令并通过文件头版权声明与类名/命名空间符合 SourceCodeTests.cs 的校验规则Fork 已与上游同步rebase 或 merge 后无冲突遵循以上流程你的贡献将能顺利通过 CI 检查、快速被维护者审阅最终进入 NLog 的master或dev分支成为这个广泛使用的 .NET 日志框架的一部分。赞分享后端运维观测【免费下载链接】NLogNLog - Flexible and Structured Logging for various .NET Platforms项目地址https://gitcode.com/gh_mirrors/nl/NLog点击查看免费下载相关推荐Astropy 贡献指南从 Issue 报告到 Pull Request 合入的完整实战手册Astropy 贡献指南从 Issue 报告到 Pull Request 合入的完整实战手册 本指南以 Astropy 仓库根目录的 CONTRIBUTING科学计算科研数据分析深入Windows内核KDU工具完整指南与实战应用深入Windows内核KDU工具完整指南与实战应用 你是否曾经想要深入了解Windows内核的工作原理却因为复杂的调试环境而望而却步你是否遇到过需要绕过驱网络安全开发工具spaCy 贡献者指南从 Issue 报告、源码构建到测试与代码规范的完整实践手册spaCy 贡献者指南从 Issue 报告、源码构建到测试与代码规范的完整实践手册 导读 本文是 spaCyPython 工业级自然语言处理库官方贡献指南人工智能NLP机器学习预训练创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考