SDL 贡献指南从提交 Issue 到合并 Pull Request 的完整开发协作流程【免费下载链接】SDLSimple DirectMedia Layer项目地址: https://gitcode.com/GitHub_Trending/sd/SDL导读本文以 SDLSimple DirectMedia Layer仓库的 docs/README-contributing.md 为主线系统梳理向 SDL 贡献代码与文档的完整流程——包括 Bug 报告规范、Fork 与 Pull Request 流程、.clang-format代码风格约束、testautomation测试套件运行方法、GitHub Actions 持续集成含sdl-ci-*提交消息标签以及基于 Doxygen 注释与wikiheaders.pl的双向文档同步机制。读完本文你将掌握一套可复用的开源项目协作方法论并能直接在本仓库中定位对应的配置与实现文件加以验证。目录Filing a GitHub issue如何提交 Issue报告 Bug建议功能增强贡献代码Fork、风格、测试与 Pull RequestFork 项目并同步上游遵循代码风格指南运行测试打开 Pull Request持续集成与 sdl-ci-* 标签贡献文档Doxygen 注释与 wiki 双向同步函数文档改头文件而不是改 wikiWiki 页面直接在线编辑Filing a GitHub issue如何提交 IssueSDL 的贡献流程从 Issue 开始。官方文档将 Issue 分为两类Bug 报告与功能增强建议。报告 Bug在创建新 Issue 之前先完成两件事去重检查确认你要报告的 Bug 是否已经出现在项目的 Issues 页面上避免重复提交点击 New Issue 按钮在 Issue 跟踪器中创建新问题。一个高质量 Bug 报告必须包含环境信息操作系统如 Linux、Windows、macOS 或各嵌入式平台与 SDL 版本可通过 include/SDL3/SDL_version.h 或运行testver测试程序确认最小复现示例尽可能提供一个可复现 Bug 的小程序。本仓库的 examples 目录与 test 目录中有大量可直接参考的独立测试程序例如最小窗口与渲染循环可参考 examples/renderer/01-clear 下的源码。建议功能增强对于功能建议官方文档要求先确认该建议是否已被提出过检查范围包括Issue 跟踪器SDL 官方论坛Discourse forum是否已有对应的 Pull Request。确认无人提出后再新建 Issue 并明确描述你希望发生的变更What change you would like to happen而不是只描述问题现象。贡献代码Fork、风格、测试与 Pull Request贡献代码的完整链路是Fork → 修改 → 本地测试 → Push → Pull Request → CI 验证。下面按官方流程逐一展开。Fork 项目并同步上游首次贡献进入项目主页点击右上角Fork按钮字段保持默认即可创建 fork随后点击Code按钮复制 git clone 链接在本地克隆你的 fork。后续贡献如果已经 fork 过无需重新 fork可以直接在网页端使用Fetch upstream按钮将上游更新拉取到你的 fork再同步到本地工作区。在本地克隆仓库后即可基于本仓库的docs/、src/、include/SDL3/等目录进行阅读与修改。遵循代码风格指南SDL 使用仓库根目录下的自定义 .clang-format 文件统一代码格式。官方文档明确要求只格式化你修改的代码区域不要一次性格式化整个文件——因为部分遗留代码尚未按新风格格式化整文件重排会制造大量无意义的 diff干扰代码审查。从 .clang-format 文件内容可以看到 SDL 代码风格的核心约定缩进IndentWidth: 4连续缩进同为 4禁止使用 TabUseTab: Never行尾使用 LFUseCRLF: false行宽ColumnLimit: 0即不强制 80 列换行避免破坏宏定义个别场景可用/* clang-format off/on */注释局部关闭格式化大括号采用BreakBeforeBraces: Custom自定义策略函数、类、结构体、枚举等定义之后换行放置开括号AfterFunction: true等而if/for/while等控制语句不换行AfterControlStatement: Neverelse前不换行指针与类型PointerAlignment: Rightchar *ptr风格宏AlignConsecutiveMacros: Consecutive会对连续宏进行对齐IfMacros与ForEachMacros中登记了 SDL 使用的特殊宏如CHECK_PARAM、wl_list_for_each、udev_list_entry_foreach等以便 clang-format 正确识别include 排序IncludeBlocks: Preserve表示不自动重排 include新版 clang-format 对应SortIncludes: Never。commit message 同样有规范要求为了让消息在 GitHub 上正确展示第一行50 字符以内的简短描述如需补充空一行后写详细描述且每行不超过 72 字符。官方示例Fix crash in SDL_FooBar. This addresses the issue #123456 by making sure Foo was successful before calling Bar.运行测试官方要求在 push 之前先在本地运行testautomation测试套件确保你的改动没有引入比改动前更多的失败用例。在本仓库中testautomation由 test/CMakeLists.txt 中的add_sdl_test_executable(testautomation ...)定义其源码由testautomation*.c系列文件组成如testautomation_audio.c、testautomation_render.c、testautomation_events.c、testautomation_math.c等见 test 目录。运行方式通常为# 配置并构建含测试 cmake -S . -B build -DSDL_TESTSON cmake --build build # 运行测试自动化套件 ctest --test-dir build -R testautomation --output-on-failure测试程序本身还支持丰富的命令行参数与内存跟踪相关的参数定义在 src/test/SDL_test_common.c--trackmem启用内存跟踪在测试结束时输出内存分配与泄漏统计对应实现位于 src/test/SDL_test_memory.c通过环境变量SDL_TRACKMEM_SYMBOL_NAMES可控制最终报告是否包含符号名见 src/test/SDL_test_memory.c 中对该环境变量的读取逻辑。打开 Pull Request进入你的 fork 页面点击Contribute按钮并选择Open Pull Request填写 Pull Request 模板如果审查者要求修改直接向你的 fork 追加新提交即可这些提交会被自动纳入原 Pull Request无需重开 PR。持续集成与 sdl-ci-* 标签官方文档说明每次 push 和/或 Pull RequestGitHub Actions 都会在大多数受支持平台上构建 SDL 与测试套件。CI 行为可以通过在 commit message 中加入 SDL 专用标签微调。四个标签的用途与仓库实现对应关系如下标签作用仓库实现依据[sdl-ci-filter GLOB]限制运行 CI 的平台例如[sdl-ci-filter msvc-*]只跑 MSVC 相关任务见 .github/workflows/build.yml 中 controller job 的注释以及 .github/workflows/create-test-plan.py 中对[sdl-ci-filter (.*)]的正则解析随后用 fnmatch 匹配JOB_SPECS中的任务 key[sdl-ci-artifacts]强制生成 SDL 构建产物可从 Actions 摘要页下载.github/workflows/create-test-plan.py 中\[sdl-ci-artifacts?\]会强制enable_artifacts True产物上传逻辑在 .github/workflows/generic.yml 的Upload binary package步骤[sdl-ci-trackmem-symbol-names]确保--trackmem生成的最终报告包含符号名.github/workflows/create-test-plan.py 中\[sdl-ci-(full-)?trackmem(-symbol-names)?\]会打开trackmem_symbol_names进而在 pretest 阶段设置SDL_TRACKMEM_SYMBOL_NAMES1[sdl-ci-ctest-args]覆盖 ctest 参数官方特别提示--repeat-until-fail N与-R NAME组合对排查不稳定测试很有用.github/workflows/create-test-plan.py 中\[sdl-ci-ctest-args? (.*)\]解析参数并写入ctest_args最终由 .github/workflows/generic.yml 的ctest --test-dir build/ ...步骤消费从 CI 结构看见 .github/workflows/build.yml 与 .github/workflows/generic.ymlCI 采用两阶段矩阵controller 任务调用create-test-plan.py根据平台定义JOB_SPECS生成测试矩阵level1 为高优先级平台level2 为其余平台level1 / level2 任务复用 .github/workflows/generic.yml在矩阵各平台Windows MSVC/MSYS2、Ubuntu、macOS、Android、Emscripten、PS2/PSP/Vita、N3DS、FreeBSD 等完整清单见create-test-plan.py中的JOB_SPECS上执行配置、构建、ctest、打包、pkg-config 校验等步骤。CI 步骤还会做额外的源码质量检查见 .github/workflows/generic.yml 的Check Sources步骤运行build-scripts/test-versioning.sh校验版本一致性、check_android_jni.py检查 Android JNI 封装、check_stdlib_usage.py检查标准库使用规范。因此提交前也建议本地关注这些约束。贡献文档Doxygen 注释与 wiki 双向同步函数文档改头文件而不是改 wiki官方文档明确API 函数的 wiki 文档是从头文件的 Doxygen 注释同步而来的。因此凡是涉及语法、函数参数、返回值、版本、相关函数的修改都必须直接改头文件位于 include/SDL3 目录而不是改 wiki 页面。这一机制由仓库根目录下的 build-scripts/wikiheaders.pl官方称之为 wikiheaders实现它是一个大型 Perl 脚本能够读取 wiki 与公开头文件并把一方的变更同步到另一方。Doxygen 注释的书写规范要点注释必须以/**开头两个星号且必须顶格写在行首第一列否则 wikiheaders 会忽略标记文本统一使用Markdown 格式避免过度标记wikiheaders 支持的标签包括\brief、\param、\returns、\sa、\since、\threadsafety、\deprecated第一行是摘要wikiheaders 会截取到第一个句号为止段落之间必须用空行分隔列表前也必须空行否则会被 wikiheaders 重新换行时并成一段以SDL_开头的符号会自动转换为 wiki 链接无需手工加链接。仓库中大量头文件遵循此规范例如 include/SDL3/SDL_timer.h 中的时间换算宏注释/** * \param S the number of seconds to convert. * \returns S, expressed in nanoseconds. * * \threadsafety It is safe to call this macro from any thread. * * \since This macro is available since SDL 3.2.0. */注意事项防止同步脚本出问题SDL_test*.h头文件不要写 Doxygen 注释它们虽然位于公开头文件目录但属于单独的测试库不被视为公开 API不应出现在 wiki 上见 docs/README-documentation-rules.md结构体/联合体/枚举的 typedef必须把名字放在第一行如typedef struct SDL_MyStruct { ... } SDL_MyStruct;因为 wikiheaders 不是完整的 C 解析器\param与\returns描述保持简短细节放入 Remarks 部分指针参数若允许为 NULL以 May be NULL. 结尾代码示例不要写进头文件而是写到 wiki 页面的## Code Examples一节仅使用 C 语言wikiheaders 不会把 wiki 侧代码示例回桥到头文件若确实需要隐藏某些片段可在头文件中使用#ifndef SDL_WIKI_DOCUMENTATION_SECTION包裹wikiheaders 会跳过但注意它不是 C 预处理器不要嵌套条件头文件内的##小节标题会被迁移到 wiki 并从头文件移除因此不要在 Doxygen 注释里使用小节标题docs目录下的README-*.md文件同样与 wiki 桥接如docs/README-linux.md会映射到 wiki 的 README-linux 页面本文所依据的docs/README-contributing.md即属于这一类。Wiki 页面直接在线编辑除函数文档以外的 wiki 内容官方建议直接在 wiki 站点上编辑打开任意页面点击页面底部的edit链接即可修改。这部分内容例如分类页面、自定义说明页不经过头文件属于 wiki 独立维护的内容改动不会反向污染头文件。小结SDL 的贡献流程可以概括为一条清晰的主线先查重再提 IssueFork 后小范围修改并遵守 .clang-format 风格push 前本地跑通 test/CMakeLists.txt 定义的testautomation套件借助 commit message 中的sdl-ci-*标签精细控制 .github/workflows 的 CI 行为文档修改则坚持头文件为源、wiki 为镜像由 build-scripts/wikiheaders.pl 保证两侧同步。这套协作规范不仅适用于 SDL 本身也为其他大型 C 语言开源项目提供了可参考的工程实践模板。【免费下载链接】SDLSimple DirectMedia Layer项目地址: https://gitcode.com/GitHub_Trending/sd/SDL创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 SDL 贡献指南：从提交 Issue 到合并 Pull Request 的完整开发协作流程
SDL 贡献指南从提交 Issue 到合并 Pull Request 的完整开发协作流程【免费下载链接】SDLSimple DirectMedia Layer项目地址: https://gitcode.com/GitHub_Trending/sd/SDL导读本文以 SDLSimple DirectMedia Layer仓库的 docs/README-contributing.md 为主线系统梳理向 SDL 贡献代码与文档的完整流程——包括 Bug 报告规范、Fork 与 Pull Request 流程、.clang-format代码风格约束、testautomation测试套件运行方法、GitHub Actions 持续集成含sdl-ci-*提交消息标签以及基于 Doxygen 注释与wikiheaders.pl的双向文档同步机制。读完本文你将掌握一套可复用的开源项目协作方法论并能直接在本仓库中定位对应的配置与实现文件加以验证。目录Filing a GitHub issue如何提交 Issue报告 Bug建议功能增强贡献代码Fork、风格、测试与 Pull RequestFork 项目并同步上游遵循代码风格指南运行测试打开 Pull Request持续集成与 sdl-ci-* 标签贡献文档Doxygen 注释与 wiki 双向同步函数文档改头文件而不是改 wikiWiki 页面直接在线编辑Filing a GitHub issue如何提交 IssueSDL 的贡献流程从 Issue 开始。官方文档将 Issue 分为两类Bug 报告与功能增强建议。报告 Bug在创建新 Issue 之前先完成两件事去重检查确认你要报告的 Bug 是否已经出现在项目的 Issues 页面上避免重复提交点击 New Issue 按钮在 Issue 跟踪器中创建新问题。一个高质量 Bug 报告必须包含环境信息操作系统如 Linux、Windows、macOS 或各嵌入式平台与 SDL 版本可通过 include/SDL3/SDL_version.h 或运行testver测试程序确认最小复现示例尽可能提供一个可复现 Bug 的小程序。本仓库的 examples 目录与 test 目录中有大量可直接参考的独立测试程序例如最小窗口与渲染循环可参考 examples/renderer/01-clear 下的源码。建议功能增强对于功能建议官方文档要求先确认该建议是否已被提出过检查范围包括Issue 跟踪器SDL 官方论坛Discourse forum是否已有对应的 Pull Request。确认无人提出后再新建 Issue 并明确描述你希望发生的变更What change you would like to happen而不是只描述问题现象。贡献代码Fork、风格、测试与 Pull Request贡献代码的完整链路是Fork → 修改 → 本地测试 → Push → Pull Request → CI 验证。下面按官方流程逐一展开。Fork 项目并同步上游首次贡献进入项目主页点击右上角Fork按钮字段保持默认即可创建 fork随后点击Code按钮复制 git clone 链接在本地克隆你的 fork。后续贡献如果已经 fork 过无需重新 fork可以直接在网页端使用Fetch upstream按钮将上游更新拉取到你的 fork再同步到本地工作区。在本地克隆仓库后即可基于本仓库的docs/、src/、include/SDL3/等目录进行阅读与修改。遵循代码风格指南SDL 使用仓库根目录下的自定义 .clang-format 文件统一代码格式。官方文档明确要求只格式化你修改的代码区域不要一次性格式化整个文件——因为部分遗留代码尚未按新风格格式化整文件重排会制造大量无意义的 diff干扰代码审查。从 .clang-format 文件内容可以看到 SDL 代码风格的核心约定缩进IndentWidth: 4连续缩进同为 4禁止使用 TabUseTab: Never行尾使用 LFUseCRLF: false行宽ColumnLimit: 0即不强制 80 列换行避免破坏宏定义个别场景可用/* clang-format off/on */注释局部关闭格式化大括号采用BreakBeforeBraces: Custom自定义策略函数、类、结构体、枚举等定义之后换行放置开括号AfterFunction: true等而if/for/while等控制语句不换行AfterControlStatement: Neverelse前不换行指针与类型PointerAlignment: Rightchar *ptr风格宏AlignConsecutiveMacros: Consecutive会对连续宏进行对齐IfMacros与ForEachMacros中登记了 SDL 使用的特殊宏如CHECK_PARAM、wl_list_for_each、udev_list_entry_foreach等以便 clang-format 正确识别include 排序IncludeBlocks: Preserve表示不自动重排 include新版 clang-format 对应SortIncludes: Never。commit message 同样有规范要求为了让消息在 GitHub 上正确展示第一行50 字符以内的简短描述如需补充空一行后写详细描述且每行不超过 72 字符。官方示例Fix crash in SDL_FooBar. This addresses the issue #123456 by making sure Foo was successful before calling Bar.运行测试官方要求在 push 之前先在本地运行testautomation测试套件确保你的改动没有引入比改动前更多的失败用例。在本仓库中testautomation由 test/CMakeLists.txt 中的add_sdl_test_executable(testautomation ...)定义其源码由testautomation*.c系列文件组成如testautomation_audio.c、testautomation_render.c、testautomation_events.c、testautomation_math.c等见 test 目录。运行方式通常为# 配置并构建含测试 cmake -S . -B build -DSDL_TESTSON cmake --build build # 运行测试自动化套件 ctest --test-dir build -R testautomation --output-on-failure测试程序本身还支持丰富的命令行参数与内存跟踪相关的参数定义在 src/test/SDL_test_common.c--trackmem启用内存跟踪在测试结束时输出内存分配与泄漏统计对应实现位于 src/test/SDL_test_memory.c通过环境变量SDL_TRACKMEM_SYMBOL_NAMES可控制最终报告是否包含符号名见 src/test/SDL_test_memory.c 中对该环境变量的读取逻辑。打开 Pull Request进入你的 fork 页面点击Contribute按钮并选择Open Pull Request填写 Pull Request 模板如果审查者要求修改直接向你的 fork 追加新提交即可这些提交会被自动纳入原 Pull Request无需重开 PR。持续集成与 sdl-ci-* 标签官方文档说明每次 push 和/或 Pull RequestGitHub Actions 都会在大多数受支持平台上构建 SDL 与测试套件。CI 行为可以通过在 commit message 中加入 SDL 专用标签微调。四个标签的用途与仓库实现对应关系如下标签作用仓库实现依据[sdl-ci-filter GLOB]限制运行 CI 的平台例如[sdl-ci-filter msvc-*]只跑 MSVC 相关任务见 .github/workflows/build.yml 中 controller job 的注释以及 .github/workflows/create-test-plan.py 中对[sdl-ci-filter (.*)]的正则解析随后用 fnmatch 匹配JOB_SPECS中的任务 key[sdl-ci-artifacts]强制生成 SDL 构建产物可从 Actions 摘要页下载.github/workflows/create-test-plan.py 中\[sdl-ci-artifacts?\]会强制enable_artifacts True产物上传逻辑在 .github/workflows/generic.yml 的Upload binary package步骤[sdl-ci-trackmem-symbol-names]确保--trackmem生成的最终报告包含符号名.github/workflows/create-test-plan.py 中\[sdl-ci-(full-)?trackmem(-symbol-names)?\]会打开trackmem_symbol_names进而在 pretest 阶段设置SDL_TRACKMEM_SYMBOL_NAMES1[sdl-ci-ctest-args]覆盖 ctest 参数官方特别提示--repeat-until-fail N与-R NAME组合对排查不稳定测试很有用.github/workflows/create-test-plan.py 中\[sdl-ci-ctest-args? (.*)\]解析参数并写入ctest_args最终由 .github/workflows/generic.yml 的ctest --test-dir build/ ...步骤消费从 CI 结构看见 .github/workflows/build.yml 与 .github/workflows/generic.ymlCI 采用两阶段矩阵controller 任务调用create-test-plan.py根据平台定义JOB_SPECS生成测试矩阵level1 为高优先级平台level2 为其余平台level1 / level2 任务复用 .github/workflows/generic.yml在矩阵各平台Windows MSVC/MSYS2、Ubuntu、macOS、Android、Emscripten、PS2/PSP/Vita、N3DS、FreeBSD 等完整清单见create-test-plan.py中的JOB_SPECS上执行配置、构建、ctest、打包、pkg-config 校验等步骤。CI 步骤还会做额外的源码质量检查见 .github/workflows/generic.yml 的Check Sources步骤运行build-scripts/test-versioning.sh校验版本一致性、check_android_jni.py检查 Android JNI 封装、check_stdlib_usage.py检查标准库使用规范。因此提交前也建议本地关注这些约束。贡献文档Doxygen 注释与 wiki 双向同步函数文档改头文件而不是改 wiki官方文档明确API 函数的 wiki 文档是从头文件的 Doxygen 注释同步而来的。因此凡是涉及语法、函数参数、返回值、版本、相关函数的修改都必须直接改头文件位于 include/SDL3 目录而不是改 wiki 页面。这一机制由仓库根目录下的 build-scripts/wikiheaders.pl官方称之为 wikiheaders实现它是一个大型 Perl 脚本能够读取 wiki 与公开头文件并把一方的变更同步到另一方。Doxygen 注释的书写规范要点注释必须以/**开头两个星号且必须顶格写在行首第一列否则 wikiheaders 会忽略标记文本统一使用Markdown 格式避免过度标记wikiheaders 支持的标签包括\brief、\param、\returns、\sa、\since、\threadsafety、\deprecated第一行是摘要wikiheaders 会截取到第一个句号为止段落之间必须用空行分隔列表前也必须空行否则会被 wikiheaders 重新换行时并成一段以SDL_开头的符号会自动转换为 wiki 链接无需手工加链接。仓库中大量头文件遵循此规范例如 include/SDL3/SDL_timer.h 中的时间换算宏注释/** * \param S the number of seconds to convert. * \returns S, expressed in nanoseconds. * * \threadsafety It is safe to call this macro from any thread. * * \since This macro is available since SDL 3.2.0. */注意事项防止同步脚本出问题SDL_test*.h头文件不要写 Doxygen 注释它们虽然位于公开头文件目录但属于单独的测试库不被视为公开 API不应出现在 wiki 上见 docs/README-documentation-rules.md结构体/联合体/枚举的 typedef必须把名字放在第一行如typedef struct SDL_MyStruct { ... } SDL_MyStruct;因为 wikiheaders 不是完整的 C 解析器\param与\returns描述保持简短细节放入 Remarks 部分指针参数若允许为 NULL以 May be NULL. 结尾代码示例不要写进头文件而是写到 wiki 页面的## Code Examples一节仅使用 C 语言wikiheaders 不会把 wiki 侧代码示例回桥到头文件若确实需要隐藏某些片段可在头文件中使用#ifndef SDL_WIKI_DOCUMENTATION_SECTION包裹wikiheaders 会跳过但注意它不是 C 预处理器不要嵌套条件头文件内的##小节标题会被迁移到 wiki 并从头文件移除因此不要在 Doxygen 注释里使用小节标题docs目录下的README-*.md文件同样与 wiki 桥接如docs/README-linux.md会映射到 wiki 的 README-linux 页面本文所依据的docs/README-contributing.md即属于这一类。Wiki 页面直接在线编辑除函数文档以外的 wiki 内容官方建议直接在 wiki 站点上编辑打开任意页面点击页面底部的edit链接即可修改。这部分内容例如分类页面、自定义说明页不经过头文件属于 wiki 独立维护的内容改动不会反向污染头文件。小结SDL 的贡献流程可以概括为一条清晰的主线先查重再提 IssueFork 后小范围修改并遵守 .clang-format 风格push 前本地跑通 test/CMakeLists.txt 定义的testautomation套件借助 commit message 中的sdl-ci-*标签精细控制 .github/workflows 的 CI 行为文档修改则坚持头文件为源、wiki 为镜像由 build-scripts/wikiheaders.pl 保证两侧同步。这套协作规范不仅适用于 SDL 本身也为其他大型 C 语言开源项目提供了可参考的工程实践模板。【免费下载链接】SDLSimple DirectMedia Layer项目地址: https://gitcode.com/GitHub_Trending/sd/SDL创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考