Vicinae 贡献指南:从提交 Issue 到合并 PR 的规范、格式与静态检查全流程

原创2026-10-08 20:38:001,424 阅读
文章标签:桌面应用开发工具

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 生成代码给出了非常明确的态度,核心要点如下:

  1. AI 生成代码与普通代码一视同仁:上述所有规则(本地测试、格式、lint)同样适用,没有任何豁免。
  2. AI 不能替代真正的理解与测试:指南原文是 "don't be lazy"(别偷懒)。不遵守指南的"懒 AI PR"将被直接拒绝。
  3. PR 描述尽量简洁:没有人会去读你写的"长篇大论",描述应直奔主题。
  4. 披露使用情况(良好实践):如果贡献大部分由 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 社区能保持"代码少而精、评审可负担"这一工程文化的基础。

登录后查看全文
vicinae