SerenityOS 贡献指南从 Issue 规范、C 编码风格到 commit hook 的完整协作实践【免费下载链接】serenityThe Serenity Operating System 项目地址: https://gitcode.com/GitHub_Trending/se/serenitySerenityOS 是一个从零自研的操作系统项目其 CONTRIBUTING.md 定义了整个社区的协作契约包括 Issue 提交流程、人类语言政策、C26 编码风格、提交信息格式、Pull Request 评审预期以及仓库内置的 pre-commit / commit-msg 钩子。本文以该文档为主线结合仓库内的 .pre-commit-config.yaml、Meta/lint-commit.sh、Meta/lint-ci.sh、Meta/check-style.py 与 Documentation/CodingStyle.md 等真实实现给出可直接落地执行的全流程贡献实操指南。贡献前的方向确认SerenityOS 对贡献者的第一要求是确保你的改动符合项目发展方向。如果你不确定应先在仓库中开启一个 Issue 讨论而不是直接提交大段代码。对于最初的一两个 Pull Request文档明确建议从小改动开始先熟悉项目与开发流程禁止以新增一个应用程序、库或其他大型组件作为首次 PR项目欢迎所有人参与文档的原话是我们玩得很开心但这是认真的那种开心——意味着协作氛围轻松、但对工程质量要求严肃。从仓库结构可以看到项目的宏大版图内核Kernel/、基础库AK/、浏览器Ladybird/以及数千个用户态程序Userland/。这也解释了为什么文档要求新贡献者从小处入手——改动必须能被维护者在合理时间内审阅清楚。沟通渠道项目的开发者沟通主阵地是 Discord 服务器https://serenityos.org/discord。文档后续多次强调 Discord 在代码评审中的实际作用未在社区打广告的 PR 可能被好奇的维护者随机合并但主动在 Discord 上宣传会顺畅得多由于 GitHub 通知量过大很多维护者关闭了 GitHub 通知、依赖 Discord 获知评审请求因此在 Discord 上例如#code-review频道询问评审远比在 GitHub 上等待有效构建类问题见下节应前往 Discord 的#build-problems频道求助。Issue 政策目标读者是开发者自己文档开宗明义与许多追求最大用户群的项目不同SerenityOS 的目标受众是其自身的开发者。因此项目对非贡献者的功能请求兴趣有限——请不要把这里当作普通软件的产品反馈渠道。提交 Bug 时请遵守以下规则一个 Issue 只描述一个 Bug。把多个问题塞进同一 Issue 会使讨论和关闭都变得不必要的复杂不要提交构建问题或其他支持请求。如果 CI 构建成功而本地失败问题大概率在你自己环境应在本地解决或去 Discord 的#build-problems频道询问不要在 Issue 里刷无意义评论玩笑或无关吐槽。成百上千人会被评论通知打扰请保持相关性裸机bare metal问题必须附带完整调试日志包括串口控制台的完整 debug log、你为解决该问题已尝试过的步骤、机器的硬件型号与相关细节帮助维护者诊断。人类语言政策像对待编程语言一样对待自然语言项目将人类语言与编程语言同等重视。以下规范适用于所有面向用户的字符串、代码、注释和提交信息官方语言为美式英语日期使用ISO 8601格式度量单位使用公制单位拼写、语法和标点必须正确语气要求权威且技术化authoritative and technical。文档鼓励大家使用拼写检查器等工具来辅助。在仓库中这一政策同样被机器强制执行——例如 Meta/lint-commit.sh 会检查提交信息中的大小写与标点而 Meta/check-style.py 会强制 C 头文件的版权头格式。测试政策能测则测修复 Bug 或添加新功能时请尽可能附带测试。这是硬性要求而非建议。仓库中测试的体量可以佐证这一政策的执行力度Tests/AK/ 下有 100 个针对基础库的测试文件如TestVector.cpp、TestString.cpp、TestHashMap.cpp而 Tests/ 目录整体覆盖了从 LibGfx 图像解码到 LibJS、Kernel 等几乎所有子系统。CI 中的 Meta/check-ak-test-files.sh 还会专门检查 AK 的测试文件是否齐备。代码提交规范Do 与 Dont应做事项Do1. 编写地道的 SerenityOS C26并在所有代码中使用AK容器。项目不使用 STL 作为主力容器库而是使用自研的 AKAuxiliary Kernel 工具库——例如Vector、String、HashMap、OwnPtr、RefPtr等。提交代码前请确保对 AK/ 的常用容器有基本了解。2. 遵循项目编码风格并使用clang-format20 或更新版本。完整的风格规范见 Documentation/CodingStyle.md底层格式规则由仓库根目录的 .clang-format 定义。要点速览维度规范正例 / 反例类/结构体/命名空间CamelCase首字母大写class FileDescriptor/class filedescriptor变量/函数snake_casesize_t buffer_size/size_t bufferSize常量SCREAMING_CASEMAX_ENTRIES成员前缀非静态成员m_、静态成员s_、全局变量g_int m_length { 0 };getter/settersetter 用set_前缀getter 用裸词out 参数 getter 用get_set_count(int)/int count() const头文件守卫一律#pragma once—const 位置east constconst 写在类型右侧Salt const m_salt;虚函数声明必须带virtual重写必须带override或finalvirtual String description() override强制转换禁止 C 风格 cast用static_cast等对应 C cast—花括号单行体可省略花括号否则整套 if/else 都要加—若你的发行版没有 clang-format 20Documentation/AdvancedBuildInstructions.md 给出了三个方案基于 apt 的发行版使用 LLVM 官方 apt 仓库安装最新 clang-format或通过 Toolchain/BuildClang.sh 编译 SerenityOS 定制的 LLVM使用编译产物Toolchain/Local/clang/bin/clang-formatpre-commit 钩子会自动识别该二进制。3. 命名要富有表现力变量、函数和类名要尽可能直观地表达其用途。4. 将改动拆分为独立的原子提交每个提交对应一个功能或修复且提交后构建、测试和系统都能正常运行。5. 确保提交基于 master 分支 rebase 过。6. 提交信息每行不超过 72 个字符并按指定格式书写第一行为主题行格式为Category: Brief description of whats being changedCategory 应为库、应用、服务或工具的名称例如LibAudio、HackStudio、Base、Kernel、ConfigServer、cat除非改动横跨目录内大量代码否则不要使用Userland或Utilities这类宽泛类别不要用具体组件名如 C 类名作类别应写进摘要里例如用LibGUI: Brief description of whats being changed in FooWidget而非FooWidget: ...多个类别可用组合如LibJSLibWebBrowser: ...主题行使用祈使语气Foo: Change the way dates work而非Foo: Changed the way dates work提交信息要用规范英语书写注意措辞与标点评审后的修改请用 amend 合并进原提交而非新提交并在推送修复后把每条评审意见标记为 resolved。仓库最近的提交历史就是活教材例如Ports/ncurses: Remove the --enable-term-driver build option——类别 祈使语气 无句号结尾完全符合上述格式。7. 对文件做实质性修改时可以鼓励但非必须添加个人版权行。8. 检查代码、注释与提交信息的拼写。9. 附带的图片资源先用optipng -strip all优化去掉无用元数据文件体积可能从数 KB 降到几百字节。禁止事项Dont提交与项目许可证2-clause BSD不兼容的代码触碰 PR 声明范围之外的任何东西在多个提交中反复迭代设计用 refactor、fix 之类模糊词汇回避解释改动内容提交信息主题行以句号结尾包含注释掉的代码用 C 编写代码——应充分利用 C 的能力不要把自己限制在标准 C 库内在尚未熟悉系统前尝试大规模架构改动无量化收益地搬动代码文档称之为 feng shui programming在系统面向用户的部分加入玩笑或有趣内容。提交钩子让规范自动化仓库根目录的 .pre-commit-config.yaml 定义了三个基于 pre-commit 框架的钩子钩子入口触发阶段作用meta-lint-cibash Meta/lint-ci.sh --no-portspre-commit运行全部 lint 脚本确保改动能通过 CI 检查meta-lint-portsMeta/lint-ports.pypre-commit仅在^Ports/文件变更时运行扫描 Ports 目录meta-lint-commitMeta/lint-commit.shcommit-msg校验提交信息格式启用方式先按 pre-commit 官方文档安装框架然后执行# 安装 pre-commit 钩子提交前运行 Meta/lint-ci.sh 与 Meta/lint-ports.py确保代码能通过 lint pre-commit install # 安装 commit-msg 钩子提交时校验提交信息能否通过 commit lint pre-commit install --hook-type commit-msg注意钩子配置中的一个工程细节meta-lint-ci通过args: [ --no-ports ]跳过了 Ports 检查而meta-lint-ports只对Ports/目录的文件触发files: ^Ports/且pass_filenames: false。正如 Meta/lint-ci.sh 注释所解释的lint-ports.py会全量扫描所有 Ports若在 pre-commit 阶段每次都跑会非常耗时因此拆成了按需触发的独立钩子。lint-ci.sh 实际执行哪些检查从 Meta/lint-ci.sh 源码看pre-commit 的meta-lint-ci钩子会串行运行 16 个检查脚本任何一个失败都会计入FAILURES并最终以非零退出码结束Meta/check-ak-test-files.shAK 测试文件完整性Meta/check-debug-flags.shdebug 标志检查Meta/check-emoji.py、Meta/check-idl-files.py、Meta/check-jbig2-json.sh、Meta/check-markdown.sh、Meta/check-newlines-at-eof.py、Meta/check-png-sizes.shMeta/check-style.py版权头、#pragma once、include 合法性详见下文Meta/lint-executable-resources.sh、Meta/lint-gml-format.sh、Meta/lint-gn.sh、Meta/lint-keymaps.py、Meta/lint-prettier.sh、Meta/lint-python.sh、Meta/lint-shell-scripts.sh此外还会尝试用构建产物./Build/lagom/bin/IPCMagicLinter校验*.ipc文件未构建时跳过最后通过 Meta/lint-clang-format.sh 对全部.cpp/.h/.mm文件就地运行 clang-format 并比对 git diff。lint-clang-format.sh会按优先级查找clang-format-20、brew --prefix llvm20下的二进制、Toolchain/Local/clang/bin/clang-format并要求显式传入--overwrite-inplace参数——这是为了让开发者清楚意识到该脚本会直接改写本地文件。check-style.py 的机器化风格检查Meta/check-style.py 是风格政策的直接执行者它用正则强制以下规则BSD-2-Clause 版权头每个.cpp/.h文件顶部必须是/* ... SPDX-License-Identifier: BSD-2-Clause */格式有少量排除名单如 AK/Checked.h#pragma once所有头文件必须包含且格式正确的#pragma once前后有空白行禁止#include LibC/...LibC 是系统库不应以目录形式被包含禁止#include complex/#include ccomplexSerenity C 代码必须使用 AK 的复数实现本地 include 必须可解析#include ...指向的文件必须真实存在。这些检查与 Documentation/CodingStyle.md 中的命名、前缀、const 位置、虚函数声明等规范一起构成了编码风格可被 CI 强制的完整闭环。lint-commit.sh 如何校验提交信息Meta/lint-commit.sh 是 commit-msg 钩子的实现它对提交信息做了非常具体的机器校验逐条对应文档中的要求拒绝 Windows 风格 CRLF 换行拒绝 merge commit提示改用 rebase主题行必须匹配Category:格式正则^(\S: )否则报缺少类别若怀疑是前一个提交的 fixup应直接 squash 掉主题行超过 72 字符即报错Revert 开头的提交豁免主题行中类别后的首词必须以大写字母或数字开头主题行以句号结尾即报错第二行必须为空行标题与正文之间的空行不可省略正文每行不得超过 72 字符URL 行豁免正文中不允许出现Signed-off-by:标记。Pull Request 评审 FAQ文档以 FAQ 形式回答了新贡献者最关心的评审问题QPR 通过了 CI多久能收到评审反馈未宣传的 PR 可能被好奇的维护者随机合并但更稳妥的方式是在 Discord 上积极互动、主动宣传。QPR 一直没人理该等多久再联系维护者如果是紧急内容可以立即 ping非紧急则在 Discord 的#code-review频道宣传你的 PR 并请求评审。Q项目维护者是谁当前维护者名单GitHub 用户名ADKaster、alimpfard、AtkinsSJ、BertalanD、GMTA、Lubrsi、LucasChollet、nico、spholz、timschumi、trflynn89。维护权是仅限邀请制且与任何特定指标无关。Q对长期无人维护的分支/PR 有策略吗有。仓库运行一个 stalebotPR 连续 21 天无人触碰会被标记为 stale再经过 7 天仍无动静则自动关闭。Q不同子系统Kernel、Browser、GUI 等有专门对接人吗理论上最合适的人选是写过与你改动相邻代码最多的人实践中在 Discord 的开发频道提问通常更简单有效因为能让更多人参与讨论。Q请求评审该用 Discord 还是 GitHub明确建议用 Discord。由于 GitHub 通知量太大很多维护者关闭了通知、依赖 Discord 获知评审请求。被遗弃的 Pull Request 如何处理偶尔有质量不错但作者失联的 PR。若 PR 本身没有问题、只是作者不回应对接项目可能会以小幅修改代码与提交信息的方式手动合入。因此文档特别鼓励贡献者开启 PR 上的Allow edits from maintainers选项方便维护者直接修正。关于意识形态类改动Serenity 的愿景是在合理范围内让尽可能多的群体协作欢迎使项目对更多人可及的贡献。但项目定位为纯粹的技术实践不寻求引发任何社会政治层面的改变项目明确避免卷入外部文化战争并可能拒绝它认为敏感如狗哨式隐语、宗教信仰——这显然离题——或现实政治人物的改动。文档也承认项目有时会判断失误但鼓励以善意的对话而非愤怒来处理分歧。小结一次合规贡献的完整动线把以上所有规范串联起来一次符合 SerenityOS 流程的贡献大致是开 Issue 确认方向或直接修一个明确的小 Bug用 SerenityOS 风格C26 AK 容器编写代码clang-format20 自动格式化尽可能为改动补充测试参考 Tests/AK/ 的模式按Category: Imperative summary格式书写提交信息72 字符、祈使语气、无句号通过 .pre-commit-config.yaml 配置的 pre-commit 与 commit-msg 钩子自检推送基于 master rebase 的原子提交在 Discord 的#code-review频道宣传 PR根据评审意见 amend 提交、标记评论为 resolved保持沟通畅通。这套由文档 钩子脚本 CI 共同构成的流程让编码风格与提交规范从纸面约定变成了可机器校验的硬约束——这正是 SerenityOS 能在庞大的代码库规模下维持高度一致性的关键工程实践。【免费下载链接】serenityThe Serenity Operating System 项目地址: https://gitcode.com/GitHub_Trending/se/serenity创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 SerenityOS 贡献指南：从 Issue 规范、C++ 编码风格到 commit hook 的完整协作实践
SerenityOS 贡献指南从 Issue 规范、C 编码风格到 commit hook 的完整协作实践【免费下载链接】serenityThe Serenity Operating System 项目地址: https://gitcode.com/GitHub_Trending/se/serenitySerenityOS 是一个从零自研的操作系统项目其 CONTRIBUTING.md 定义了整个社区的协作契约包括 Issue 提交流程、人类语言政策、C26 编码风格、提交信息格式、Pull Request 评审预期以及仓库内置的 pre-commit / commit-msg 钩子。本文以该文档为主线结合仓库内的 .pre-commit-config.yaml、Meta/lint-commit.sh、Meta/lint-ci.sh、Meta/check-style.py 与 Documentation/CodingStyle.md 等真实实现给出可直接落地执行的全流程贡献实操指南。贡献前的方向确认SerenityOS 对贡献者的第一要求是确保你的改动符合项目发展方向。如果你不确定应先在仓库中开启一个 Issue 讨论而不是直接提交大段代码。对于最初的一两个 Pull Request文档明确建议从小改动开始先熟悉项目与开发流程禁止以新增一个应用程序、库或其他大型组件作为首次 PR项目欢迎所有人参与文档的原话是我们玩得很开心但这是认真的那种开心——意味着协作氛围轻松、但对工程质量要求严肃。从仓库结构可以看到项目的宏大版图内核Kernel/、基础库AK/、浏览器Ladybird/以及数千个用户态程序Userland/。这也解释了为什么文档要求新贡献者从小处入手——改动必须能被维护者在合理时间内审阅清楚。沟通渠道项目的开发者沟通主阵地是 Discord 服务器https://serenityos.org/discord。文档后续多次强调 Discord 在代码评审中的实际作用未在社区打广告的 PR 可能被好奇的维护者随机合并但主动在 Discord 上宣传会顺畅得多由于 GitHub 通知量过大很多维护者关闭了 GitHub 通知、依赖 Discord 获知评审请求因此在 Discord 上例如#code-review频道询问评审远比在 GitHub 上等待有效构建类问题见下节应前往 Discord 的#build-problems频道求助。Issue 政策目标读者是开发者自己文档开宗明义与许多追求最大用户群的项目不同SerenityOS 的目标受众是其自身的开发者。因此项目对非贡献者的功能请求兴趣有限——请不要把这里当作普通软件的产品反馈渠道。提交 Bug 时请遵守以下规则一个 Issue 只描述一个 Bug。把多个问题塞进同一 Issue 会使讨论和关闭都变得不必要的复杂不要提交构建问题或其他支持请求。如果 CI 构建成功而本地失败问题大概率在你自己环境应在本地解决或去 Discord 的#build-problems频道询问不要在 Issue 里刷无意义评论玩笑或无关吐槽。成百上千人会被评论通知打扰请保持相关性裸机bare metal问题必须附带完整调试日志包括串口控制台的完整 debug log、你为解决该问题已尝试过的步骤、机器的硬件型号与相关细节帮助维护者诊断。人类语言政策像对待编程语言一样对待自然语言项目将人类语言与编程语言同等重视。以下规范适用于所有面向用户的字符串、代码、注释和提交信息官方语言为美式英语日期使用ISO 8601格式度量单位使用公制单位拼写、语法和标点必须正确语气要求权威且技术化authoritative and technical。文档鼓励大家使用拼写检查器等工具来辅助。在仓库中这一政策同样被机器强制执行——例如 Meta/lint-commit.sh 会检查提交信息中的大小写与标点而 Meta/check-style.py 会强制 C 头文件的版权头格式。测试政策能测则测修复 Bug 或添加新功能时请尽可能附带测试。这是硬性要求而非建议。仓库中测试的体量可以佐证这一政策的执行力度Tests/AK/ 下有 100 个针对基础库的测试文件如TestVector.cpp、TestString.cpp、TestHashMap.cpp而 Tests/ 目录整体覆盖了从 LibGfx 图像解码到 LibJS、Kernel 等几乎所有子系统。CI 中的 Meta/check-ak-test-files.sh 还会专门检查 AK 的测试文件是否齐备。代码提交规范Do 与 Dont应做事项Do1. 编写地道的 SerenityOS C26并在所有代码中使用AK容器。项目不使用 STL 作为主力容器库而是使用自研的 AKAuxiliary Kernel 工具库——例如Vector、String、HashMap、OwnPtr、RefPtr等。提交代码前请确保对 AK/ 的常用容器有基本了解。2. 遵循项目编码风格并使用clang-format20 或更新版本。完整的风格规范见 Documentation/CodingStyle.md底层格式规则由仓库根目录的 .clang-format 定义。要点速览维度规范正例 / 反例类/结构体/命名空间CamelCase首字母大写class FileDescriptor/class filedescriptor变量/函数snake_casesize_t buffer_size/size_t bufferSize常量SCREAMING_CASEMAX_ENTRIES成员前缀非静态成员m_、静态成员s_、全局变量g_int m_length { 0 };getter/settersetter 用set_前缀getter 用裸词out 参数 getter 用get_set_count(int)/int count() const头文件守卫一律#pragma once—const 位置east constconst 写在类型右侧Salt const m_salt;虚函数声明必须带virtual重写必须带override或finalvirtual String description() override强制转换禁止 C 风格 cast用static_cast等对应 C cast—花括号单行体可省略花括号否则整套 if/else 都要加—若你的发行版没有 clang-format 20Documentation/AdvancedBuildInstructions.md 给出了三个方案基于 apt 的发行版使用 LLVM 官方 apt 仓库安装最新 clang-format或通过 Toolchain/BuildClang.sh 编译 SerenityOS 定制的 LLVM使用编译产物Toolchain/Local/clang/bin/clang-formatpre-commit 钩子会自动识别该二进制。3. 命名要富有表现力变量、函数和类名要尽可能直观地表达其用途。4. 将改动拆分为独立的原子提交每个提交对应一个功能或修复且提交后构建、测试和系统都能正常运行。5. 确保提交基于 master 分支 rebase 过。6. 提交信息每行不超过 72 个字符并按指定格式书写第一行为主题行格式为Category: Brief description of whats being changedCategory 应为库、应用、服务或工具的名称例如LibAudio、HackStudio、Base、Kernel、ConfigServer、cat除非改动横跨目录内大量代码否则不要使用Userland或Utilities这类宽泛类别不要用具体组件名如 C 类名作类别应写进摘要里例如用LibGUI: Brief description of whats being changed in FooWidget而非FooWidget: ...多个类别可用组合如LibJSLibWebBrowser: ...主题行使用祈使语气Foo: Change the way dates work而非Foo: Changed the way dates work提交信息要用规范英语书写注意措辞与标点评审后的修改请用 amend 合并进原提交而非新提交并在推送修复后把每条评审意见标记为 resolved。仓库最近的提交历史就是活教材例如Ports/ncurses: Remove the --enable-term-driver build option——类别 祈使语气 无句号结尾完全符合上述格式。7. 对文件做实质性修改时可以鼓励但非必须添加个人版权行。8. 检查代码、注释与提交信息的拼写。9. 附带的图片资源先用optipng -strip all优化去掉无用元数据文件体积可能从数 KB 降到几百字节。禁止事项Dont提交与项目许可证2-clause BSD不兼容的代码触碰 PR 声明范围之外的任何东西在多个提交中反复迭代设计用 refactor、fix 之类模糊词汇回避解释改动内容提交信息主题行以句号结尾包含注释掉的代码用 C 编写代码——应充分利用 C 的能力不要把自己限制在标准 C 库内在尚未熟悉系统前尝试大规模架构改动无量化收益地搬动代码文档称之为 feng shui programming在系统面向用户的部分加入玩笑或有趣内容。提交钩子让规范自动化仓库根目录的 .pre-commit-config.yaml 定义了三个基于 pre-commit 框架的钩子钩子入口触发阶段作用meta-lint-cibash Meta/lint-ci.sh --no-portspre-commit运行全部 lint 脚本确保改动能通过 CI 检查meta-lint-portsMeta/lint-ports.pypre-commit仅在^Ports/文件变更时运行扫描 Ports 目录meta-lint-commitMeta/lint-commit.shcommit-msg校验提交信息格式启用方式先按 pre-commit 官方文档安装框架然后执行# 安装 pre-commit 钩子提交前运行 Meta/lint-ci.sh 与 Meta/lint-ports.py确保代码能通过 lint pre-commit install # 安装 commit-msg 钩子提交时校验提交信息能否通过 commit lint pre-commit install --hook-type commit-msg注意钩子配置中的一个工程细节meta-lint-ci通过args: [ --no-ports ]跳过了 Ports 检查而meta-lint-ports只对Ports/目录的文件触发files: ^Ports/且pass_filenames: false。正如 Meta/lint-ci.sh 注释所解释的lint-ports.py会全量扫描所有 Ports若在 pre-commit 阶段每次都跑会非常耗时因此拆成了按需触发的独立钩子。lint-ci.sh 实际执行哪些检查从 Meta/lint-ci.sh 源码看pre-commit 的meta-lint-ci钩子会串行运行 16 个检查脚本任何一个失败都会计入FAILURES并最终以非零退出码结束Meta/check-ak-test-files.shAK 测试文件完整性Meta/check-debug-flags.shdebug 标志检查Meta/check-emoji.py、Meta/check-idl-files.py、Meta/check-jbig2-json.sh、Meta/check-markdown.sh、Meta/check-newlines-at-eof.py、Meta/check-png-sizes.shMeta/check-style.py版权头、#pragma once、include 合法性详见下文Meta/lint-executable-resources.sh、Meta/lint-gml-format.sh、Meta/lint-gn.sh、Meta/lint-keymaps.py、Meta/lint-prettier.sh、Meta/lint-python.sh、Meta/lint-shell-scripts.sh此外还会尝试用构建产物./Build/lagom/bin/IPCMagicLinter校验*.ipc文件未构建时跳过最后通过 Meta/lint-clang-format.sh 对全部.cpp/.h/.mm文件就地运行 clang-format 并比对 git diff。lint-clang-format.sh会按优先级查找clang-format-20、brew --prefix llvm20下的二进制、Toolchain/Local/clang/bin/clang-format并要求显式传入--overwrite-inplace参数——这是为了让开发者清楚意识到该脚本会直接改写本地文件。check-style.py 的机器化风格检查Meta/check-style.py 是风格政策的直接执行者它用正则强制以下规则BSD-2-Clause 版权头每个.cpp/.h文件顶部必须是/* ... SPDX-License-Identifier: BSD-2-Clause */格式有少量排除名单如 AK/Checked.h#pragma once所有头文件必须包含且格式正确的#pragma once前后有空白行禁止#include LibC/...LibC 是系统库不应以目录形式被包含禁止#include complex/#include ccomplexSerenity C 代码必须使用 AK 的复数实现本地 include 必须可解析#include ...指向的文件必须真实存在。这些检查与 Documentation/CodingStyle.md 中的命名、前缀、const 位置、虚函数声明等规范一起构成了编码风格可被 CI 强制的完整闭环。lint-commit.sh 如何校验提交信息Meta/lint-commit.sh 是 commit-msg 钩子的实现它对提交信息做了非常具体的机器校验逐条对应文档中的要求拒绝 Windows 风格 CRLF 换行拒绝 merge commit提示改用 rebase主题行必须匹配Category:格式正则^(\S: )否则报缺少类别若怀疑是前一个提交的 fixup应直接 squash 掉主题行超过 72 字符即报错Revert 开头的提交豁免主题行中类别后的首词必须以大写字母或数字开头主题行以句号结尾即报错第二行必须为空行标题与正文之间的空行不可省略正文每行不得超过 72 字符URL 行豁免正文中不允许出现Signed-off-by:标记。Pull Request 评审 FAQ文档以 FAQ 形式回答了新贡献者最关心的评审问题QPR 通过了 CI多久能收到评审反馈未宣传的 PR 可能被好奇的维护者随机合并但更稳妥的方式是在 Discord 上积极互动、主动宣传。QPR 一直没人理该等多久再联系维护者如果是紧急内容可以立即 ping非紧急则在 Discord 的#code-review频道宣传你的 PR 并请求评审。Q项目维护者是谁当前维护者名单GitHub 用户名ADKaster、alimpfard、AtkinsSJ、BertalanD、GMTA、Lubrsi、LucasChollet、nico、spholz、timschumi、trflynn89。维护权是仅限邀请制且与任何特定指标无关。Q对长期无人维护的分支/PR 有策略吗有。仓库运行一个 stalebotPR 连续 21 天无人触碰会被标记为 stale再经过 7 天仍无动静则自动关闭。Q不同子系统Kernel、Browser、GUI 等有专门对接人吗理论上最合适的人选是写过与你改动相邻代码最多的人实践中在 Discord 的开发频道提问通常更简单有效因为能让更多人参与讨论。Q请求评审该用 Discord 还是 GitHub明确建议用 Discord。由于 GitHub 通知量太大很多维护者关闭了通知、依赖 Discord 获知评审请求。被遗弃的 Pull Request 如何处理偶尔有质量不错但作者失联的 PR。若 PR 本身没有问题、只是作者不回应对接项目可能会以小幅修改代码与提交信息的方式手动合入。因此文档特别鼓励贡献者开启 PR 上的Allow edits from maintainers选项方便维护者直接修正。关于意识形态类改动Serenity 的愿景是在合理范围内让尽可能多的群体协作欢迎使项目对更多人可及的贡献。但项目定位为纯粹的技术实践不寻求引发任何社会政治层面的改变项目明确避免卷入外部文化战争并可能拒绝它认为敏感如狗哨式隐语、宗教信仰——这显然离题——或现实政治人物的改动。文档也承认项目有时会判断失误但鼓励以善意的对话而非愤怒来处理分歧。小结一次合规贡献的完整动线把以上所有规范串联起来一次符合 SerenityOS 流程的贡献大致是开 Issue 确认方向或直接修一个明确的小 Bug用 SerenityOS 风格C26 AK 容器编写代码clang-format20 自动格式化尽可能为改动补充测试参考 Tests/AK/ 的模式按Category: Imperative summary格式书写提交信息72 字符、祈使语气、无句号通过 .pre-commit-config.yaml 配置的 pre-commit 与 commit-msg 钩子自检推送基于 master rebase 的原子提交在 Discord 的#code-review频道宣传 PR根据评审意见 amend 提交、标记评论为 resolved保持沟通畅通。这套由文档 钩子脚本 CI 共同构成的流程让编码风格与提交规范从纸面约定变成了可机器校验的硬约束——这正是 SerenityOS 能在庞大的代码库规模下维持高度一致性的关键工程实践。【免费下载链接】serenityThe Serenity Operating System 项目地址: https://gitcode.com/GitHub_Trending/se/serenity创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考