niri 贡献指南：从 Issue 讨论、PR 测试审查到高质量补丁提交的完整实践

niri 贡献指南：从 Issue 讨论、PR 测试审查到高质量补丁提交的完整实践

【免费下载链接】niriA scrollable-tiling Wayland compositor.项目地址: https://gitcode.com/GitHub_Trending/ni/niri

niri 是一个基于 Smithay 的滚动平铺（scrollable-tiling）Wayland 合成器，随着项目成长，维护者越来越需要社区在 Issue 处理、Pull Request 测试与代码审查、以及补丁编写上分担工作。本文基于仓库根目录的 CONTRIBUTING.md，并结合 开发文档、布局随机化测试、Cargo.toml 等仓库源码，系统讲解非开发者如何参与 Issue 讨论、如何严谨地测试与审查 PR、以及如何写出既符合项目设计方向又能快速通过审查的补丁。读完本文，你将掌握一套可复用的 niri 协作流程与质量保障方法论。

参与 Issues 与 Discussions：无需编程经验也能贡献

即便没有编程知识，也可以通过 Issues 与 Discussions 帮助大量新老用户，这也是最轻量级的入门方式。核心工作是"分流"与"澄清"：

• 回答问题：在 GitHub Issues 和 Discussions 中为他人答疑。
• 标记重复：主动检查并指出重复的 issue。
• 甄别问题归属：很多 issue 表面出现在 niri 中，实际却是应用 bug、硬件问题或配置问题。贡献者应当帮助判断问题属于哪一层：
  • 在非 Smithay 系合成器（sway、KDE/KWin、GNOME/Mutter）上尝试复现；若问题同样出现，多半是应用 bug。
  • 在另一个Smithay 系合成器（如 cosmic-comp、anvil）上复现；若只有 Smithay 合成器出问题，则可能是Smithay 库自身的 bug。
  • 确保在所有合成器上都测试应用的Wayland 版本——当存在 X11$DISPLAY时，应用可能静默使用 X11 路径，导致结果失真。
  • X11 应用的问题应上报给 xwayland-satellite。在不同合成器上测试 xwayland-satellite 时，务必使用它自己提供的$DISPLAY，而不是其他合成器内置 Xwayland 的$DISPLAY，否则测试的是错误的 X11 实现。
  • 测试完成后，在 issue 中说明哪些环境能复现、哪些不能，若原 issue 缺少复现步骤，则补充精确的复现步骤。
• 亲自复现：在自己的机器上尝试复现 issue，并写明结果。
• 为 issue 点赞：用 👍 表达支持，帮助维护者判断优先级。
• 引导新需求：新用户的 idea 与 feature request 应导向 Discussions。
• 关闭无效 issue：确认是重复、应用 bug、硬件问题或配置问题后，主动关闭它。

这一过程直接关系到 niri 的质量闭环：准确的 issue 分流能让维护者把时间花在真正的合成器缺陷上。

测试与审查 Pull Request：项目最需要帮助的环节

维护者明确表示，PR 数量已超出个人空闲时间的管理能力，因此测试与审查是社区最稀缺的贡献。

如何严谨地测试一个 PR

挑选一个感兴趣的 PR，构建后实际运行体验。关于如何运行 niri 测试构建，可参考仓库内的 Development:-Developing-niri.md，其中给出了三种由轻到重的本地验证方式：

1. 嵌套窗口运行：开发期间最主要的方式，把 niri 当作一个嵌套窗口跑起来，便于快速迭代。
2. 切换 TTY 运行：切到另一个 TTY 直接运行 niri。
3. 作为主合成器使用：功能基本成型后，正常安装发行版包，再用sudo cp ./target/release/niri /usr/bin/niri覆盖二进制做完整验证——前提是必须清楚如何回滚到可用版本。RPM 系发行版可用cargo generate-rpm生成本地构建的 RPM 包（对应配置见 Cargo.toml 中的[package.metadata.generate-rpm]）。

测试要"挑剔"到极致，niri 追求的是打磨完好的功能，因此即使是动画卡顿这类小问题也要指出：

• 设想奇怪边缘情况与意外交互并逐一尝试，确认行为合理。
• 故意尝试破坏功能，检查它在异常输入下是否表现良好。
• 只要适用，就切换不同输入设备：键盘、鼠标、触控板、数位板、触摸屏。
• 留意任何新增的性能回退。

对bug 修复类 PR，务必先在当前版本复现 bug，再在 PR 构建中重复同样步骤，验证修复生效；同时测试相似或相关的边缘情况，确认修复没有引入新问题。

测试结果要写进 PR 评论：发现的任何问题，或一切正常。作者更新代码后应重新测试，确认你提出的问题已被解决。即使别人已经测过也不要犹豫——不同的人非常容易踩到不同的问题。

如何审查 PR 代码

代码审查是维护者最需要的帮助，因为 PR 数量大且耗时。任何代码被合入过 niri 的人都可以审查，但这不是硬性要求——即使不熟悉 Rust，也可能发现逻辑问题。

审查时检查以下几点：

• 代码整体是否合理，各分支是否覆盖了边缘情况。
• 是否有作者遗漏处理的场景。
• 代码是否融入 niri 整体风格：观察周边代码与同类模块（例如实现新协议时对照其他协议实现），遵循既有风格与结构。这需要理解 niri 的设计原则。
• 是否有无关改动，更适合拆成独立 PR。
• wiki 是否同步更新：例如新增配置选项时，应在 Configuration:-Overview.md 系列文档中给出示例，并标注正确的 Since 版本注解。

将发现以 review comment 形式指出（记得提交 review）。反馈要建设性且尊重他人——很多人可能是 Rust 新手。作者处理完评论后再次检查；一切就绪时明确说出来，让维护者知道有人已经看过。同样，即使别人审查过也不要犹豫，多一双眼睛总能发现更多问题。

编写 Pull Request：让补丁既正确又好审

遵循设计方向，保持聚焦

• 新功能必须符合 niri 的设计方向，理想情况下应存在事先讨论并达成共识的 issue 或 discussion，避免凭空引入未对齐的方案。
• PR 应聚焦单一功能或单一 bug 修复，不夹带无关改动。

提交拆分与历史整理

• 尽量把改动拆成小而自包含的提交：每个提交都应能独立构建并通过测试。这既方便审查，也便于将来git bisect定位回归。
• 回应 review 意见时，尽量把修改直接 squash 进相关提交；若改动较大或不够明确，可暂时以追加提交的形式放置，但定稿前务必 squash 并整理历史。
• 更新主分支时用 rebase 而不是 merge，并尽量把"同步主分支"的 rebase 与其他改动分开 force-push——这类同步通常不具审查价值，分开后审查者可轻松跳过。
• 处理大型功能时，维护者通常的做法是：先写一个大而杂的初始提交，随代码成型再逐步拆出更小的自包含改动。可以参考 git-rebase.io 这类指南学习拆分提交与清理历史。

测试与格式化

• 提交前务必运行测试并用cargo +nightly fmt --all格式化代码。仓库根目录的 rustfmt.toml 定义了格式化约定，例如imports_granularity = "Module"、group_imports = "StdExternalCrate"、wrap_comments = true、comment_width = 100，nightly 格式化用于满足这些自定义规则。
• 新增布局操作时，把它加入随机化测试的Op枚举——这样会自动纳入随机化测试覆盖。仓库中该枚举位于 src/layout/tests.rs，通过#[derive(Arbitrary)]与 proptest 配合生成随机的输出增删、窗口增删、聚焦、全屏等操作序列；此外还有every_op数组（见 src/layout/tests.rs）用于穷举每个操作在初始状态下的不 panic 验证。
• 奇怪的 Wayland 处理，在src/tests/下补充客户端-服务端测试非常有用，例如 src/tests/window_opening.rs 中就有针对窗口打开/全屏/最大化行为的测试。
• 手动全面测试，涵盖边缘情况与怪异交互（见上文 Testing 小节）。

如何让 PR 更快被审查

• 保持小而自包含，避免混入多个无关改动。
• 拆成小而自包含的提交。
• 新功能、新选项、行为变更事先讨论，确保设计有共识。
• 开 PR 时清楚写明：它做了什么、解决什么问题、如何测试。
• 遵守本文其余建议。
• 打开 PR 时确保勾选"Allow edits from maintainers"，让维护者可在合并前做最终微调。

测试命令速查（来自开发文档）

仓库 开发文档 给出了与上述流程配套的具体命令：

# 运行主 crate 与子 crate（niri-config、niri-ipc、niri-visual-tests）的全部测试 cargo test --all # 布局随机化等慢测试默认被跳过，用 RUN_SLOW_TESTS 开启 env RUN_SLOW_TESTS=1 cargo test --all # 长时间跑随机化测试以覆盖更多输入（提交前的推荐用法） env RUN_SLOW_TESTS=1 PROPTEST_CASES=200000 PROPTEST_MAX_GLOBAL_REJECTS=200000 RUST_BACKTRACE=1 cargo test --release --all

此外，niri-visual-tests子 crate（见 niri-visual-tests/README.md）是一个仅用于开发的 GTK 应用，运行硬编码的视觉测试用例，使用 mock 窗口配合真实的布局与渲染代码，尤其适合验证动画效果，可配合cargo run直接运行。

AI 贡献政策：LLM 输出必须人工把关

仓库对使用 LLM 辅助贡献有明确且严格的政策：使用 LLM 生成的贡献（issue、评论、PR）时，检查和清理其输出是你的责任，就像对待其他任何工具一样，这份时间必须由你来花。具体而言：

• PR：维护者能看出 PR 主要由 LLM 生成时，通常会拒绝优先处理——基于其过往审查经验，这类 PR 的审查和收尾往往要消耗远超平均水平的时间精力。仓库中总有大量人工编写的 PR 优先级更高。
• Issue：LLM 生成的 issue 通常有大量赘述与无关细节，读者会很快失去耐心。应当清理文本，只保留真正重要的细节。
• 评论：使用 LLM 撰写 issue 评论时，你必须核实评论言之有物、确有贡献、无无谓重复。

补充：理解 niri 的日志级别与性能定位

在测试与审查中，正确解读日志能显著提升定位效率。niri 使用tracing记录日志（详见 开发文档），各级别含义如下：

• error!：可恢复的编程错误与 bug。Wayland 合成器崩溃会拖垮整个会话，因此能恢复就尽量恢复并记error!。日志中出现 ERROR 必然意味着 bug。
• warn!：发生了不好但仍属"可能"的事情，例如用户配置错误（配置解析错误应以warn!提示）。
• info!：正常运行中最重要的消息，RUST_LOG=niri=info运行时不至于让用户想关掉日志。
• debug!：正常运行的次要消息，隐藏后不应影响使用体验。
• trace!：一切对调试有用但过于刷屏或高开销的信息，release 构建中会被编译掉。

若怀疑性能问题，可用 Tracy 分析器（对应 Cargo.toml 中的profile-with-tracy*特性）：

# 按需采集：仅当 Tracy 连接时才记录，可当主合成器日常使用 cargo build --release --features=profile-with-tracy-ondemand # 始终采集：适合分析启动过程或 niri CLI，但不适合作为主合成器 cargo build --release --features=profile-with-tracy

在源码中为函数加let _span = tracy_client::span!("some_function");即可让该函数出现在 Tracy 中（仓库中 src/backend/mod.rs、src/a11y.rs 等大量函数均有此类插桩示例），还可通过--features=profile-with-tracy-allocations开启内存分配分析。

结语

niri 的协作体系围绕"准确分流 issue、苛刻测试 PR、认真审查代码、小而自包含的补丁"四个支柱运转。对社区贡献者而言，从 Issues 讨论 起步、到测试与审查、再到编写与维护高质量 PR，每一步都有明确的可执行标准；而对使用 AI 工具的贡献者，核心红线是：LLM 只是工具，质量责任始终在人。理解并实践这套流程，你不仅能帮项目分担繁重的维护工作，也能在参与中深入理解 niri 的布局算法、Smithay 架构与测试策略，成为项目生态中真正有价值的协作者。

【免费下载链接】niriA scrollable-tiling Wayland compositor.项目地址: https://gitcode.com/GitHub_Trending/ni/niri