curl 贡献实战指南代码风格、测试用例、REUSE 合规与提交信息的完整规范【免费下载链接】curlA command line tool and library for transferring data with URL syntax, supporting DICT, FILE, FTP, FTPS, GOPHER, GOPHERS, HTTP, HTTPS, IMAP, IMAPS, LDAP, LDAPS, MQTT, MQTTS, POP3, POP3S, RTSP, SCP, SFTP, SMB, SMBS, SMTP, SMTPS, TELNET, TFTP, WS and WSS. libcurl offers a myriad of powerful features项目地址: https://gitcode.com/GitHub_Trending/cu/curl本文以 CONTRIBUTE.md 为骨架系统梳理 curl 项目的贡献全流程如何遵循被make checksrc强制约束的 C 代码风格、如何为每个新特性补齐测试用例、pull request 如何通过与 CI 验证及 feature window 机制最终被合并以及 curl 特有的 commit message 格式、REUSE 许可证合规检查和对 AI 辅助贡献的明确要求。读完本文你将掌握一份从第一次提交补丁到成为 push access 贡献者的可操作路线图并能直接对照仓库中的脚本与测试体系落地执行。1. 贡献前的准备社区渠道、许可与必读材料1.1 加入社区curl 项目偏好问题与讨论在邮件列表上进行而不是直接发给个人。在提问前应阅读邮件列表礼仪规范——仓库内即有 MAIL-ETIQUETTE.md 记录了完整的列表行为规范在提交补丁之前则应先通读本文档。如果对代码侧开发感兴趣curl 在 IRC 频道#curllibera.chat也有社区驻留。1.2 许可与版权规则以代码形式向 curl 贡献时需遵守以下许可规则源自 CONTRIBUTE.md “License and copyright”一节你的改动与新代码默认采用与 curl/libcurl 相同的许可证除非另行说明并达成一致如果加入较大的一块代码可以让该文件或文件组使用不同的许可证前提是它不强制改动包的其他部分、且选择合理。这类“独立部分”不允许使用 GPL项目不希望 copyleft 传导给 libcurl 用户但必须使用“GPL 兼容”的许可证保证 GPL 环境下的使用者能正常使用 libcurl修改已有源码不会改变原文件的版权归属版权仍归原始作者或其受让人提交补丁即表示你拥有该代码的处置权并获雇主等允许将其交给项目。项目会尽量署名贡献者因此贡献时请始终提供真实全名。仓库的许可证文本保存在 LICENSES/ 目录含 curl 许可证 等根级 REUSE.toml 则按 REUSE 规范描述无法直接加注释的文件的许可状态。1.3 必读材料清单原文档要求贡献者在动手前阅读源码与 man 页面——命令行选项的 man 页面源文件集中在 docs/cmdline-opts/libcurl API 文档在 docs/libcurl/均以 markdown 编写再渲染为 man 页与 HTML内部实现文档——docs/internals/ 目录包含 28 篇模块级文档如 CODE_STYLE.md、CHECKSRC.md、NEW-PROTOCOL.md 等入口是 docs/internals/README.mddocs/TODO.md 与 docs/KNOWN_BUGS.md以及 git 中的最新提交记录关注 curl-library 邮件列表的近期讨论了解正在进行的工作。2. 写出一个好补丁Write a good patch2.1 遵循既定代码风格并跑通make checksrcC 代码必须遵循项目既定的 C 代码风格指南。风格统一比个人口味更重要它让代码库像“一个人写的”也便于评审与调试。风格指南的几条硬性规则包括缩进只用空格、每层两个空格禁止 TAB只写 C89 代码因此//注释不被允许一律使用/* */源码行宽不得超过 79 列if/while/for的开括号与关键字同行函数开括号单独成行else换行书写。在提交任何改动之前文档明确要求运行make checksrc。该目标定义在根 Makefile.am会依次进入lib、src、tests、include/curl、docs/examples、projects各子目录执行检查底层工具是 scripts/checksrc.pl。需要说明的是checksrc并不校验完整风格指南它只捕获贡献者最常犯的典型错误——但“如果它抱怨了你就还有功课要做”。从 docs/internals/CHECKSRC.md 可以看到它覆盖的主要检查项摘取其中对日常编码影响最大的几类警告名检查内容BANNEDFUNC使用了被禁函数sprintf、vsprintf、strcat、strncat、gets绝不允许出现在 curl 源码中SNPRINTF检测到snprintf()项目偏好内部替代实现curl_msnprintf()LONGLINE行宽超过 79 列TABS出现 TAB 字符CPPCOMMENTS出现非 C89 的//注释ASTERISKNOSPACE/ASTERISKSPACE指针声明应为char *name形式EQUALSNULL在if/while中比较 NULL项目偏好!varUSESAFEFREEcurlx_free(var)后手动置 NULL应改用curlx_safefree()COPYRIGHT文件缺少版权声明checksrc还支持在源码内联控制豁免/* !checksrc! disable LONGLINE all */ /* ... 一段确实无法缩短的长行 ... */ /* !checksrc! enable LONGLINE */也可以只豁免 N 次例如/* !checksrc! disable LONGLINE 1 */表示忽略一次长行警告后自动恢复。此外还有默认关闭的扩展警告如COPYRIGHTYEAR可通过在目录中放置.checksrc文件按enable EXTENDEDWARNING逐行启用。2.2 不做全局性翻修Non-clobbering All Over开发新功能或修 bug 时不要顺手“翻新”无关的源码和函数——其他开发者很可能正在改同一个文件甚至同一个函数全局改动会制造大量冲突。文档给出的具体建议是引入全新功能时尽量写进新的源文件修 bug 时一次只修一个 bug拆成独立补丁分别提交。2.3 拆分变更Write Separate Changes文档用一个很现实的反例说明拆分的重要性一个号称修复 11 个问题的巨型补丁若其中 10 个与讨论结论不符或已被别的方式修复合并者就得从代码山里手工剥离那 1 个有效改动工作量巨大。因此每个修复都应有自己的补丁/commit 和各自的描述使维护者可以选择性地采纳。拆分变更还让日后的git bisect定位回归问题顺畅得多。2.4 基于最新源码打补丁请尽量用当前可获得的最新源码作为补丁基线最优是从 git 仓库拿到最新代码使用最新发布包也可以。基线越新维护者合并时的工作量越小“Making quality changes”一节再次强调补丁要尽可能基于最新源码。2.5 附带文档文档坦承“写文档是枯燥的也是许多开源项目的大问题”但要求每个贡献都附带一小段对修复内容或新特性的描述便于快速并入包内文档。curl 的文档体系是man 页面与站点 HTML 大多由 markdown / 纯 ASCII 源文件渲染生成因此在 docs/cmdline-opts/命令行选项、docs/libcurl/API下维护 markdown 源文件即可。2.6 每个新特性都要带测试用例自测试套件建立以来项目可以快速验证主要功能符合预期。为保持并改善这一状态所有新增功能和函数都必须进入测试套件每个新增特性至少要有一个能验证“它按文档工作”的有效测试用例。如果某处确实难以写测试则必须在提交说明中准确解释你如何以其他方式测试与验证了改动。仓库中的测试体系可以直接对应理解tests/ 目录是套件主体tests/runtests.pl 是测试运行器TFLAGS中的参数直接透传给它tests/libtest/ 下约 276 个.c文件是基于 libcurl API 的测试程序tests/unit/ 下约 79 个.c文件是针对内部组件的单元测试tests/data/ 下有 2000 余个测试数据文件test**编号文件即各测试用例的请求/期望定义测试服务器脚本如 tests/http-server.pl、tests/ftpserver.pl、tests/rtspserver.pl 等支撑对应协议用例。运行方式见 docs/tests/TEST-SUITE.md在仓库根目录执行./configure make make test指定用例可用make test TFLAGS303 410加速可用make test TFLAGS-j10失败后到tests/log目录查看 stdout/stderr 与测试服务器输出。3. 提交变更Pull Request 工作流3.1 优先使用 Pull Request向 curl 提交改动有两条路径在 GitHub 发起 pull request或把纯补丁发到 curl-library 邮件列表。如果走邮件列表大概率会有人帮你把补丁转成 pull request让 CI 先完整验证再合并——并且要预期后续评审反馈会转到 GitHub 上进行。项目强烈偏好 pull request 而非邮件补丁原因是 PR 天然是规整的 git commit易于合并、易于跟踪不会淹没在邮件洪流中。3.2 CI 会自动验证每一个 PR每个 pull request 都会被自动测试验证内容见 docs/tests/CI.md包括在 Linux、macOS、Windows、BSD 上用 clang 与 gcc、autotools 与 CMake、树内与树外构建且无警告Windows 上各受支持 MSVC 版本可构建基础代码风格规则即 checksrc测试套件 100% 通过发布包dist tarball可用不同 TLS 后端与编译选项可编译并过测试。任何一项失败都会显示红叉提交者有责任修复若看不懂失败原因应提问求助。若失败是依赖服务临时不可用如包下载服务宕机导致的偶发失败可以通过 push 新 commit 或 force-push 重新触发测试。评审后调整 PR 时建议把 commitsquash起来方便维护者看完整的更新版本。3.3needs-votes标签一个 PR 可能被维护者打上needs-votes标签含义是除满足所有其他检查外它还需要更多“用户支持票”——可以是留言表达支持也可以是 GitHub 上的 thumbs-up 反应。3.4 审批与 feature window若你认为 PR 已就绪却迟迟未被批准可以主动询问PR 获批后由维护者合并如果获批后长时间未被合并也可以主动询问“还能做什么”对新特性类 PR合并要求feature window处于打开状态。从 docs/CONTRIBUTE.md 看这通常是上一次发布 10 天之后开始、持续约三周的窗口期窗口期提交的新特性 PR 必须等窗口打开才能合并。docs/RELEASE-PROCEDURE.md 中对应的发布流程说明发布后 3 周/21 天内为 feature window与这一描述相互印证若补丁按本文所有建议操作数周后仍无回应考虑重新提交到列表或更好——改为 pull request。3.5 Push Access频繁贡献者可能被授予 git 仓库的 push 权限从而直接推送而不是走 PR/邮件。前提是先提交过多份高质量补丁。文档明确表示如果你想申请可以直接问。4. Commit Message 规范curl 项目有明确的 commit message 格式---- start ---- [area]: [short line describing the main effect] -- empty line -- [full description, no wider than 72 columns that describes as much as possible as to why this change is made, and possibly what things it fixes and everything else that is related, -- end --具体要求第一行是对改动的简洁描述应当理想地可直接作为 RELEASE NOTES 中的一行项目根目录即有 RELEASE-NOTES 文件承接这类内容使用祈使句、现在时change而不是 changed 或 changes首字母不大写行尾不加句号。[area]可以是http2、cookies、openssl之类没有固定列表但建议与相关改动使用同一个 area 以保持一致。4.1 关键词Keywords文档列出了一组用于指向相关工作、改进信息密度的关键词Follow-up to {shorthash}—— 本提交修复或延续某个先前 commit 时使用若不是小而明显的修复再加一行Ref:指向那个 commit 的 PR 或 issue然后空一行Bug: URL—— 指向报告来源或更相关的讨论对 GitHub issue 则改用FixesFixes #1234—— 修复某个 GitHub issuecommit 合并后 GitHub 会自动关闭该 issueCloses #1234—— 合并某个 GitHub PR合并后自动关闭Ref: #1234—— 关联某个可能已关闭的issue 或 PRRef: URL—— 指向该 commit 的更多信息若引用的是其他 bug tracker 的 bug 则用Bug:Approved-by: John Doe—— 署名批准该 PR 的人Authored-by: John Doe—— 署名代码原作者仅当你无法使用git commit --author...时才用Signed-off-by: John Doe—— 项目不用这个但看到了也不用费心删除whatever-else-by:—— 署名所有协助者尽量从Acked-by:、Assisted-by:、Co-authored-by:、Found-by:、Reported-by:、Reviewed-by:、Suggested-by:、Tested-by:中选择保持格式一致。署名细节同样有讲究提交他人作品时记得用--author提交前确认自己 git 的 user/email 配置正确多人参与时每人一行不需要给自己署名除非用了--author隐藏了自己的身份header 中不要包含他人邮箱地址以免被垃圾邮件利用——除非邮箱已在先前 commit 中公开写{userid} on github是可以的。5. 版权与许可证信息的维护REUSE 合规每个 PR 和 commit 都会触发名为REUSE compliance / check的 CI 作业验证所有文件的REUSE 状态依然合规。这意味着每个文件都必须清晰声明许可证与版权首选方式是在文件内使用标准 curl 源码头含SPDX-License-Identifier。仓库中几乎每个 C 文件都长这样例如 lib/llist.c 的文件头完整声明了版权声明、许可说明并以SPDX-License-Identifier: curl收尾如果无法加注释不可注释的文件等可以用较小的头或把该文件的许可信息写进根目录的 REUSE.toml。该文件按 REUSE 规范声明SPDX-PackageName curl并以[[annotations]]段落批量覆盖如 RELEASE-NOTES、tests/data/ 下的测试数据、projects/Windows/ 等无法直接注释的路径统一标注SPDX-License-Identifier curl与版权持有者也可以手动运行 REUSE helper tool 的reuse lint命令自检合规状态。6. AI 辅助贡献的明确边界CONTRIBUTE.md 专门设有一节 “On AI use in curl”这是贡献者必须注意的合规要点6.1 安全报告与其他问题如果用 AI 工具发现了 curl 中的问题必须在报告里披露这一事实报告前必须仔细复核确认问题真实存在且行为如 AI 所述——AI 工具频繁产出不准确或虚构的结果不建议把 AI 生成的报告直接粘贴给项目这类报告通常冗长、不切题且常带虚构细节。正确做法是自己验证属实后用自己的话重写报告解释你学到的问题所在让 AI 生成的不准确之处尽早被过滤项目对每条安全报告都会优先调查这消耗大量时间精力虚构的安全报告会挤占真实工作。提交伪造报告的账号会被立即封禁。6.2 Pull Request提交内容即授予项目按原样使用、并按 curl 许可证再分发的权限确保所提交内容允许这样分发无未许可代码的责任在作者这一点与是否使用 AI 无关基本判断标准是如果别人能一眼看出贡献是 AI 辅助完成的你还需要再下功夫项目可以接受 AI 辅助写的代码但它仍必须遵循编码标准、写清楚、有文档、带测试用例满足一切常规要求。6.3 翻译项目鼓励并欢迎借助翻译工具用非母语提交报告、文本与文档但 AI 翻译有时会让文字带“机器味”可考虑主动说明使用了此类工具——否则维护者可能误把翻译文本当作“AI 垃圾”而错误拒掉。7. 贡献流程速查阶段关键动作仓库内依据准备读内部文档、TODO、KNOWN_BUGS邮件列表提问先读礼仪docs/internals/README.md、docs/MAIL-ETIQUETTE.md编码遵循代码风格新特性写新文件一 bug 一补丁docs/internals/CODE_STYLE.md自查make checksrc为特性补测试用例并本地跑通scripts/checksrc.pl、Makefile.am、docs/tests/TEST-SUITE.md提交标准头 SPDX无法注释的文件更新 REUSE.tomlREUSE.toml、lib/llist.cPR按 CI 反馈修复评审后 squash注意needs-votes与 feature windowdocs/tests/CI.md、docs/RELEASE-PROCEDURE.md提交信息[area]: 短描述 72 列正文使用Fixes/Ref:等关键词docs/CONTRIBUTE.md按以上规范走完一轮贡献后持续提交高质量补丁即可向维护者申请 push access进入直接推送的阶段。【免费下载链接】curlA command line tool and library for transferring data with URL syntax, supporting DICT, FILE, FTP, FTPS, GOPHER, GOPHERS, HTTP, HTTPS, IMAP, IMAPS, LDAP, LDAPS, MQTT, MQTTS, POP3, POP3S, RTSP, SCP, SFTP, SMB, SMBS, SMTP, SMTPS, TELNET, TFTP, WS and WSS. libcurl offers a myriad of powerful features项目地址: https://gitcode.com/GitHub_Trending/cu/curl创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考