Vicinae 贡献指南:从提交 Issue 到合并 PR 的规范、格式与静态检查全流程
Vicinae 贡献指南:从提交 Issue 到合并 PR 的规范、格式与静态检查全流程
Vicinae 是一个基于 QtQuick 的原生桌面启动器(command palette),仓库以 C++ 承担业务逻辑、QML 承担界面呈现,并用 React/TypeScript 驱动扩展 API。本文以仓库根目录的 CONTRIBUTING.md 为骨架,结合 AGENTS.md、根目录 Makefile、.clang-format、.clang-tidy 及 src/server 下的内置命令实现,完整讲解向 Vicinae 提交 bug 报告与代码贡献时必须遵循的规范:Issue 提交流程、代码通用准则、clang-format/clang-tidy 格式化与静态检查体系,以及针对 AI 生成代码的评审口径。读完本文,你将清楚掌握"如何提交一份会被认真对待的 Issue"和"如何写出能通过评审的 C++/QML/TypeScript 补丁"。
一、总览:贡献的两种途径
Vicinae 的贡献者指南开宗明义:这份文档包含你在贡献之前(无论是以 bug 报告还是代码的形式)必须遵循的一组准则。仓库本身是 C++23 + QML 的多平台项目(Linux / macOS / Windows),其开发工作流在不同平台上有明确分工:
- UNIX 系使用
make dev进入开发模式; - Windows 使用
cmake --preset windows-relwithdebinfo(仅在必要时才做完整 debug 构建)。
这两条开发入口同时记录在 AGENTS.md 中,与贡献指南中的"所有提交的代码都需要本地测试"直接呼应:任何补丁在提交前,都应先在对应平台的开发模式下完成构建与验证。
二、提交 Issue 的正确姿势
2.1 Issue 追踪与查重
所有 Issue 都通过仓库内置的 GitHub Issue 追踪器管理。如果拿不准自己的问题是否值得开一个新 Issue,可以选择先创建 GitHub Discussion 或加入 Discord 服务器讨论,避免污染 Issue 列表。在打开 Issue 之前,务必先做一次快速搜索,确认自己没有创建重复条目——这是开源仓库维护者最在意的基本礼仪之一。
2.2 遵循 Issue 模板与内置报告命令
提交时请确保遵循仓库提供的 Issue 模板。指南特别强调:bug 类 Issue 应优先使用 Vicinae 内置的 "Report Bug" 命令直接提交,除非该 bug 导致 Vicinae 服务器无法启动。
这一要求在源码中有完整实现。report-bug-command.hpp 定义了内置命令 report-bug(id 为 "report-bug",名称为 "Report a Vicinae Bug"),其作用是用预填好的相关信息跳转到 Vicinae 的 Issue 创建页面;它还接收一个可选的 title 参数,并带有 create issue 关键字便于搜索命中。
预填信息来自 bug-report-url.hpp 中的 ISSUE_TEMPLATE,会自动拼接以下系统信息,让维护者无需反复追问环境细节:
- Version(版本号)与 Build info(构建信息,来自
generated/version.h) - Provenance(来源渠道)
- OS(操作系统)与 QT Platform
- DE(桌面环境,来自
internal/os-release.hpp)
模板正文还固定包含 "Describe the bug"、"To Reproduce"、"Expected behavior" 等小节。也就是说,用内置命令提交 bug 时,版本、OS、桌面环境等关键环境信息会被自动带出,你只需要描述复现步骤与预期行为即可。该命令的入口在设置页的 About 页面(AboutSettingsPage.qml 中 Settings.reportBug()),底层的 reportBug() 实现在 settings-window.cpp。
2.3 扩展 bug 与安全问题走专门通道
- 如果 bug 涉及官方 Vicinae 扩展商店中发布的扩展,应在其扩展仓库(vicinaehq/extensions)中提交 Issue,而不是主仓库——主仓库的 Issue 只跟踪 Vicinae 本体的问题。
- 如果怀疑是严重的安全问题,不要直接开公开 Issue,应通过 vicinaehq 组织页面上列出的联系邮箱私下联系维护团队。
三、贡献代码的通用准则
3.1 Less is more:小步提交
指南的第一条原则直白而实用:"Less is more"——每一行新代码都意味着项目额外的维护成本,体量巨大的 PR 被接受的概率更低,尤其是那些包含重大架构决策、且之前从未讨论过的改动。
因此,如果你打算做一个大改动,建议先加入 Discord 服务器,在 dev 频道中与维护者充分讨论后再动手。这既能避免方向性返工,也能让后续评审更顺畅。
3.2 本地测试是硬性要求
所有提交的代码都需要在本地测试通过。构建说明与开发技巧见官方文档的 build 页面;如前所述,开发入口在 UNIX 上为 make dev,在 Windows 上为 cmake --preset windows-relwithdebinfo(AGENTS.md)。注意:仓库是只读的,这里的构建与测试指的是在你自己的本地工作副本中进行。
四、格式化与 Lint:硬性门槛
Vicinae 的格式化体系是"分语言、多工具、可一键执行"的:
| 语言/文件 | 格式化工具 | 触发方式 |
|---|---|---|
C++(.cpp / .hpp / .mm) |
clang-format |
make format(内部 clang-format 目标) |
QML(.qml) |
qmlformat |
make format(内部 qmlformat 目标) |
TypeScript(src/typescript) |
biome format --write |
make format(内部 tsfmt 目标) |
4.1 clang-format:代码风格的唯一标准
格式化统一由仓库根目录的 .clang-format 文件规定,所有贡献必须尊重该格式。根目录 .clang-format 的关键配置为:
BasedOnStyle: LLVM——以 LLVM 风格为基础;ColumnLimit: 110——单行最长 110 列;AllowShortIfStatementsOnASingleLine: true、AllowShortBlocksOnASingleLine: Always、AllowShortFunctionsOnASingleLine: All——允许短语句/代码块/函数单行书写;SortIncludes: false——头文件不自动排序(include 顺序规则见下文 4.4)。
你可以运行 make format 一次性格式化整个项目的所有文件;大多数现代 IDE 也能根据 .clang-format 自动拾取规则并在保存时自动格式化。对照 Makefile 可以看到 clang-format 目标的真实行为:它遍历 ./src 下所有 *.cpp、*.hpp、*.mm 文件,按 -n 10 -P $(NPROC) 并行调用 clang-format -i 原地改写。
如果想要只检查不改写(CI / 提交前自检场景),可运行 make check-format:它对同样范围的文件执行 clang-format --dry-run -Werror,任一文件格式漂移即返回非零退出码(Makefile)。
4.2 需要跳过的文件:.clang-format-ignore
部分 vendored 依赖与生成代码不应被重新格式化,它们记录在根目录 .clang-format-ignore 中,包括:
src/lib/common/include/common/CLI11.hpp(第三方 CLI 库)src/lib/emoji/include/emoji/generated/*等生成目录src/server/src/lib/toml.hpp
需要注意:.clang-format-ignore 只有 clang-format >= 18 才被支持。Windows 下的格式化脚本 scripts/format.ps1 对此专门做了版本兜底:优先使用 $env:CLANG_FORMAT 覆盖,其次寻找 VS 2022 自带的 LLVM,若 PATH 上的版本低于 18 则尝试切换,并输出警告(旧版本会误改生成文件、造成无谓的 diff)。
4.3 Windows 贡献者:scripts/format.ps1
Windows 用户没有 GNU make / POSIX shell 时,可以运行 PowerShell 脚本 scripts/format.ps1 作为 make format 的等价物:
pwsh scripts/format.ps1 # 原地格式化整个源码树
pwsh scripts/format.ps1 -Check # 仅校验 C++ 格式(等价 make check-format),漂移时以非零退出码失败
该脚本同样覆盖 clang-format(C++)、qmlformat(QML)与 biome(TypeScript)三段,并以批处理方式(每批 40 个文件)调用工具以规避 Windows 命令行长度限制。
4.4 注释纪律
指南对注释的态度非常明确:把注释数量控制在严格的最低限度,好代码不需要大量注释。但也有例外:如果你觉得自己的解决方案不理想、可以改进,或者依赖某种"奇怪的 hack",那么用注释记录下来是被鼓励的。项目目前不使用文档生成器,因此不需要为生成文档而写注释。
AGENTS.md 进一步细化了编码风格中的注释与书写规则:
- QObject 类中
Q_OBJECT、Q_PROPERTY、Q_INVOKABLE、signals按顺序放在类顶部; - include 顺序:系统头文件在前,本地头文件在后;
- 头文件保护统一使用
#pragma once; - 字符串类型内部用
std::string,QString只出现在 Qt 边界; - 常量使用
UPPER_SNAKE_CASE。
4.5 clang-tidy:新代码必须通过
仓库最近才添加了 .clang-tidy 配置文件,目前并未全局强制启用——因为还有大量代码尚未迁移。但新代码必须对照这些规则检查。多数 IDE 仅凭 .clang-format / .clang-tidy 文件的存在就能自动提供对应的智能提示(intellisense)。
从根目录 .clang-tidy 可以看到这套检查体系的取向:
WarningsAsErrors将所有告警视为错误(唯一豁免bugprone-unchecked-optional-access);- 启用的检查族包括
bugprone-*、concurrency-*、cppcoreguidelines-*、google-global-names-in-headers、misc-*、modernize-*、performance-*、portability-*、readability-*等,同时针对项目实际逐条关闭了不合适的子规则(如cppcoreguidelines-avoid-magic-numbers、readability-magic-numbers、modernize-use-trailing-return-type等); CheckOptions中强制了命名规范:类/结构体/枚举使用CamelCase,函数使用camelBack(.clang-tidy);HeaderFilterRegex排除了 vendored 的CLI11、toml、rang头文件。
关于 lint 违规的豁免策略,AGENTS.md 给出了更细的指引:个别违规在特定场景下可被接受,应使用 //NOLINTBEGIN(<rule>) 与 //NOLINTEND(<rule>) 成对注释包裹;行内 //NOLINT 注释一般不被鼓励(格式化后可能错位失效);若 NOLINT 指令本身无效(例如 STL 内部误报),才考虑在本地 .clang-tidy 配置中显式关闭对应检查。
4.6 别忘了 QML 与 TypeScript
虽然 CONTRIBUTING.md 只点名了 clang-format,但完整的 make format(Makefile)实际上串联了三段:qmlformat tsfmt clang-format。其中 QML 还有独立的 make qmllint 用于运行 linter(AGENTS.md),QML 内的 JavaScript 应尽量使用 ES6 语法,且逻辑只服务于呈现关注点(metrics 计算、hover 信号等)。TypeScript 部分统一由 biome format --write . 格式化(Makefile)。
五、AI 生成代码的处理政策
CONTRIBUTING.md 对 AI 生成代码给出了非常明确的态度,核心要点如下:
- AI 生成代码与普通代码一视同仁:上述所有规则(本地测试、格式、lint)同样适用,没有任何豁免。
- AI 不能替代真正的理解与测试:指南原文是 "don't be lazy"(别偷懒)。不遵守指南的"懒 AI PR"将被直接拒绝。
- PR 描述尽量简洁:没有人会去读你写的"长篇大论",描述应直奔主题。
- 披露使用情况(良好实践):如果贡献大部分由 AI 生成,建议在 PR 中注明使用了哪个模型或工具——这有助于维护者评估与复核。
结合前文 4.5 节可以理解背后的工程逻辑:Vicinae 的 clang-tidy 检查族(bugprone-*、cppcoreguidelines-*、performance-* 等)本质上就是为捕获 AI 代码常见的"看似正确实则危险"的模式而设,因此"新代码必须通过 clang-tidy 规则"对 AI 生成代码尤为关键。
六、总结:一份合格贡献的检查清单
综合 CONTRIBUTING.md 与仓库实现,提交前可以对照这份清单自查:
- [ ] 是否为重复 Issue?是否遵循 Issue 模板?
- [ ] bug 是否通过 Vicinae 内置 "Report Bug" 命令提交(除非服务器无法启动)?扩展相关 bug 是否已转到扩展仓库?
- [ ] 大改动是否已在 dev 频道提前讨论过?
- [ ] 代码是否在本地(UNIX 用
make dev,Windows 用cmake --preset windows-relwithdebinfo)完成构建与测试? - [ ] 是否运行了
make format(Windows 用pwsh scripts/format.ps1)并通过make check-format(或-Check)? - [ ] 新代码是否通过了
.clang-tidy规则检查(必要时用NOLINTBEGIN/END成对豁免)? - [ ] 注释是否精简到最小、是否只在解释"非理想方案/hack"时使用?
- [ ] 若为 AI 生成代码:是否真实理解并测试过、PR 描述是否简洁、是否注明了所用模型?
遵循这些约定,你的 Issue 和 PR 就能以维护者最习惯的形态进入评审流程,这也是 Vicinae 社区能保持"代码少而精、评审可负担"这一工程文化的基础。