ARTICLE DETAIL

资讯详情

深耕网站视觉设计与运营推广的一线实战洞察。

Zeek 贡献者指南:从提交规范到长期 Fork 的格式化冲突治理

Zeek 贡献者指南:从提交规范到长期 Fork 的格式化冲突治理 网络安全网络IDS【免费下载链接】zeekZeek is a powerful network analysis framework that is much different from the typical IDS you may know.项目地址https://gitcode.com/gh_mirrors/ze/zeek点击查看免费下载导读本文面向希望为 Zeek 网络分析框架仓库根目录贡献代码、文档或长期维护自有分支的开发者系统讲解 Zeek 官方贡献流程、代码与文档风格约定、内存错误检查手段并重点剖析如何借助仓库内固化的pre-commit格式化配置在长期 Fork 的merge与rebase两种工作流中低成本化解格式冲突。读完本文你将掌握 Zeek 提交贡献前的全部自检项并能在自己的 Zeek 分支上复现官方推荐的格式化同步策略。贡献总览从何处入手Zeek 的贡献入口在根目录 CONTRIBUTING.md它明确说明贡献的形式远不止代码文档反馈、社区支持、测试等都算贡献且不要求你是专家才能参与。该文件建议读者先阅读官方的 Contribution Guide 获取从入门到深入的参与路径技术类贡献的细节则可查阅 doc/advanced/devel/contributors.rst即本文对应的源文档生成的开发者贡献指南。围绕贡献者仓库还维护了若干配套文档CODE_OF_CONDUCT.md社区行为准则保证协作环境友好SECURITY.md 与 SECURITY_MODEL.md安全问题的上报渠道与安全模型说明AGENTS.md 与 AI_POLICY.md面向 AI 辅助开发者的仓库约定。编码风格与约定靠配置而非靠自觉Zeek 的 C/C、Python、CMake 乃至 Zeek 脚本风格并非写在 Wiki 里供人背诵而是以版本化配置文件的形式固化在仓库根目录由pre-commit统一编排执行。仓库当前使用的格式化相关配置包括配置文件用途.pre-commit-config.yaml编排所有格式化与 Lint 工具的主配置.clang-formatC/C 代码格式化另有 src/spicy/.clang-format 供 Spicy 侧使用.cmake-format.jsonCMake 文件格式化ruff.tomlPython 代码 Lint 与格式化规则说明源文档 contributors.rst 中列出的 Python 格式化配置为.style.yapfYAPF而在当前仓库快照中该文件已不存在Python 侧的实际格式化与静态检查已由ruff接管见 ruff.toml 与 pre-commit 中的ruff-check/ruff-format两个 hook这正是配置随版本演进的实例。一次跑完全部检查pre-commit run --all-files只要仓库中存在这些配置文件执行如下命令即可安装全部格式化器并按当前配置重排所有文件pre-commit run --all-files从 .pre-commit-config.yaml 可以看到 Zeek 实际启用的 hook 清单它们构成了提交前的完整质量门禁license本地 hookci/license-header.py检查.h/.c/.cpp/.cc/.spicy/.evt源文件是否含See the file COPYING in the main distribution directory for copyright.这一版权头缺失即报错退出btest-command-commented本地 hook确保testing/btest/下所有TEST-命令行均已注释防止测试指令被误执行check-added-large-filespre-commit-hooksv6.0.0拒绝新增超过 200KB 的大文件clang-formatmirrors-clang-format v20.1.8格式化 C/C/JSON 文件排除src/3rdparty/与testing/btest/Baselineshfmtv3.12.0.1以-i 4 -ci参数格式化 shell 脚本ruff-check / ruff-formatruff-pre-commit v0.12.8Python 的 Lint 与格式化ruff-check自动带--fixcmake-formatv0.6.13格式化 CMake 文件typosv1.35.3拼写检查排除 CHANGES、测试目录等噪音较大的路径spicy-formatv0.27.1格式化.spicy/.evt文件。clang-format 的具体规则要点Zeek 对 C 的格式化要求可以从 .clang-format 中读出关键参数ColumnLimit: 120单行最长 120 列IndentWidth: 4、TabWidth: 4、UseTab: Never缩进 4 空格且禁用 TabPointerAlignment: Left指针/引用符号靠左int* pBreakBeforeBraces: Custom配合BraceWrapping各子项函数、类、命名空间等大括号不另起一行else前换行最重要的特色是IncludeCategories通过正则把#include分为 0~6 个优先级分组并自动排序——zeek-config.h排在最前Priority 1C 风格头文件Priority 2、C 风格头文件Priority 3、zeek/前缀头文件Priority 4、其余包括构建目录自动生成代码Priority 5、第三方 doctestPriority 6依次排列SortIncludes: true保证每次提交头文件顺序一致。cmake-format 与 ruff 的细则.cmake-format.json 中Zeek 为cmake-format注册了 Zeek/Spicy 特有的命令zeek_add_plugin、spicy_add_analyzer、FindRequiredPackage等以保证参数换行风格统一line_width为 100且always_wrap强制spicy_add_analyzer与zeek_add_plugin两个命令始终换行。ruff.toml 则声明target-version py39排除auxil/目录Lint 规则选取C4可读性、Fpyflakes 错误、I导入排序、ISC隐式字符串拼接、UPpyupgrade 现代化五类。通用文档结构与流程Zeek 文档体系的维护说明集中在根目录 doc/README其要点如下文档是Read the Docs 上的 Sphinx 项目顶层 doc/conf.py 承载全部 Sphinx 配置新增文档需把文件加入某个toctree目录树才能被收录Zeek 通过 doc/ext/zeek.py 自定义了 reST 指令如:zeek:see:用于链接 Zeekygen 自动生成的脚本文档自动生成的文档大多位于scripts/目录下文件名形如autogenerated.或以.rst结尾对自动生成内容的修改应改在 Zeek 源脚本本身例如要改scripts/base/init-bare.zeek.rst应去编辑scripts/base/init-bare.zeekZeekygen 参考文档由仓库 CI.github/workflows/generate-docs.yml自动生成通常无需手动提交生成产物。本地构建文档依赖 Python ≥ 3.10、Sphinx、Read the Docs Sphinx Theme 与 GitPython可用pip3 install -r requirements.txt一次性安装依赖清单见 doc/requirements.txt。在doc/目录执行make后HTML 产物会软链接到doc/build/html浏览器打开其中的index.html即可预览。文档风格与约定Zeek 的文档风格约定语言风格、示例规范、reST 用法在官方 Wiki 的 Documentation Style and Conventions 页面维护。仓库内的实际范本包括 doc/tutorial入门教程含大量可直接运行的.zeek示例与.diff、doc/frameworksBroker、Input、Intel、Logging、Supervisor、Telemetry 等框架指南以及 doc/scripts由 Zeekygen 生成的脚本参考。撰写新文档时跟随这些既有章节的语气与结构是最稳妥的做法。检查内存错误与泄漏官方在 Wiki 的 Checking for Memory Errors and Leaks 页面维护了内存检查的完整流程。在仓库内可以看到相应的工程支撑单测框架基于 doctestsrc/3rdparty/doctest.hCI 提供线程/内存消毒器支持ci/tsan_suppressions.txt 是 ThreadSanitizer 的抑制列表模糊测试体系位于 src/fuzzers覆盖 DNS、WebSocket、packet 与 generic analyzer 等入口配合 ci/test-fuzzers.sh 在 CI 中运行涉及 C 内存与并发相关的实现可结合 src/IntrusivePtr.h、src/threading 等源码理解对象的生命周期管理方式。建议在提交涉及内存管理的改动前至少在本地用 ASan/UBSan 构建并运行相关 btest 用例测试框架见 testing/btest。长期 Fork 维护格式化冲突的根治策略本节是 contributors.rst 的技术核心Zeek 的代码格式由仓库跟踪的配置自动强制上游更新这些配置会引发全仓重排长期存活的分支会因此产生大量格式 diff 与合并冲突。文档给出了两条经官方验证的治理路线。核心前提配置即格式格式的唯一事实来源是仓库根目录的四个配置文件.pre-commit-config.yaml、.clang-format、.style.yapf/现为ruff、.cmake-format.json。pre-commit run --all-files会安装所需格式化器并依据当前配置重排全部文件因此只要让分支的格式基线跟上上游后续合入上游代码时就不会再冒出格式噪音。路线 Amaster 定期 merge 进 Fork如果选择把 Zeek 的master分支定期合并进 Fork冲突只会在合并点出现一次且其解决结果会被 Git 记录## 从 master 取回并暂存最新版配置文件。 git checkout master -- .pre-commit-config.yaml .clang-format .style.yapf .cmake-format.json ## 按新配置重排 Fork 全仓。 pre-commit run -a ## 记录 Fork 重排后的状态。 git add -u git commit -m Reformat # 合并 master照常解决合并冲突。 git merge master要点先格式化一次并提交再执行git merge master。由于格式基线已与上游对齐合并时遇到的就只是真正的语义冲突。注按当前仓库实际情况若你的 Fork 基线来自新版本命令中的.style.yapf应替换为仓库实际跟踪的 Python 格式化配置现为ruff相关文件。路线 BFork 定期 rebase 到 masterrebase 场景下若目标分支曾被整体重排单个 diff hunk 可能无法干净应用。冲突最少的方式是先把 Fork 按上游风格重排不拉入任何上游改动再 rebase 上游并解决语义冲突# 创建提交更新配置文件。 git checkout master -- .pre-commit-config.yaml .clang-format .style.yapf .cmake-format.json git commit -m Bump formatter configurations # 设 Fork 分支自上游提交 FORK_COMMIT 分出把Bump formatter configurations # 这一提交交互式移到 Fork 补丁列表最前暂不 rebase master。 git rebase -i FORK_COMMIT # 按基线配置重排所有提交用 --exec 在每个补丁应用后执行 pre-commit。 # 若 git rebase 检测到未提交的改动会自动停下以便检查并应用。 git rebase -i FORK_COMMIT --exec pre-commit run --all-files # 停住时检查改动并暂存。 git add -u # 继续 rebase会提示输入提交信息并修正最后一个补丁。 git rebase --continue # Fork 现已按上游风格格式化。rebase 到 master # 并从补丁列表中丢弃 Bump formatter configurations 这个补丁。 git rebase -i master流程解读前置配置提交先提交仅更新格式化配置的补丁为后续逐提交重排提供基线交互式重排git rebase -i FORK_COMMIT --exec pre-commit run --all-files会在每个补丁应用后强制执行全仓格式化rebase检测到未提交改动会暂停方便你git add -u后再git rebase --continue收尾Fork 格式与上游一致后正常 rebase 到master并在交互列表中 drop 掉那个配置补丁——它完成了使命不该留在最终历史里。配套机制.git-blame-ignore-revs仓库根目录的 .git-blame-ignore-revs 列出了历次大规模重排提交如Reformat the world、clang-format: Reformat Zeek in Spicy style等 13 条。配合 Git 的git blame --ignore-revs-file .git-blame-ignore-revs使用可以把纯格式化提交从 blame 结果中剔除避免谁动了这一行的追溯被格式刷屏污染。长期 Fork 维护者同样可以把本分支的重排提交追加到该文件保持 git 历史可读。综合检查清单提交前过一遍结合 contributors.rst、.pre-commit-config.yaml 与 CONTRIBUTING.md一次合格的 Zeek 贡献提交至少应满足格式pre-commit run --all-files全绿含 license 头检查、clang-format、ruff、shfmt、cmake-format、spicy-format、typos测试相关改动在 testing/btest 下有对应用例并本地通过新增/修改脚本的TEST-命令行保持注释状态文档用户可见的行为变化同步更新 doc 下对应章节自动生成内容改在源文件而非.rst产物上历史若基于长期 Fork 提交先按上文路线 A/B 完成格式化对齐避免把格式噪音混入功能补丁安全涉及 C/C 内存管理的改动建议配合消毒器与 fuzzerssrc/fuzzers自检后再提交。小结Zeek 把代码质量门禁完全配置化地锁定在仓库中C 由.clang-format120 列、4 空格、按优先级排序 includePython 由ruffCMake 由.cmake-format.json全部由.pre-commit-config.yaml编排。对于长期存活的分支先对齐格式基线、再合入/变基上游的两条官方工作流能显著降低合并成本配合.git-blame-ignore-revs忽略纯格式提交还能保住 git 历史的可追溯性。无论你是提交单个补丁还是维护一个长期 Fork本文的检查清单与命令序列都可以直接作为实操模板。赞分享网络安全网络IDS【免费下载链接】zeekZeek is a powerful network analysis framework that is much different from the typical IDS you may know.项目地址https://gitcode.com/gh_mirrors/ze/zeek点击查看免费下载相关推荐BRVAH发布与混淆指南proguard-rules配置与Maven Central发布完整流程BRVAH发布与混淆指南proguard rules配置与Maven Central发布完整流程 BRVAHBaseRecyclerViewAndroidH移动开发UI组件终极pipreqs贡献者指南从代码规范到完美提交的完整流程终极pipreqs贡献者指南从代码规范到完美提交的完整流程 pipreqs是一款能够根据项目导入自动生成pip requirements.txt文件的实用工具开发工具CLIRomM贡献者指南代码规范与提交信息格式RomM贡献者指南代码规范与提交信息格式 作为一款美观、强大的自托管ROM管理器RomM全称ROM Manager其开源社区的健康发展离不开每位贡献者后端前端创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考
返回列表