跳到主要内容

贡献指南

感谢你有兴趣为 NyaTerm 做出贡献。

开始之前​

  1. 阅读仓库根目录的 AGENTS.md 和 CONTRIBUTING.md。
  2. 按照 开发环境搭建 配置 Rust 和平台依赖。
  3. 查看 Issues，确认问题和预期行为。

选择正确的 crate​

  • 纯模型、解析、兼容格式和策略放在 nyaterm-core。
  • 数据库执行和兼容性读取放在 nyaterm-store。
  • PTY、SSH、SFTP、Telnet、串口、隧道和传输运行时放在 nyaterm-transport。
  • 终端状态机与快照放在 nyaterm-terminal；GPUI 终端绘制放在 nyaterm-terminal-gpui。
  • GPUI 状态、视图和后台任务协调放在 nyaterm-desktop。
  • 共享 GPUI 控件和主题集成放在 nyaterm-ui。
  • RDP/VNC 会话管理、输入模型和 IPC 合约放在 nyaterm-remote-desktop；协议解码器只放在 nyaterm-rdp-helper 和 nyaterm-vnc-helper。

跨 crate 修改应保持 adapter 小而明确，并确保每份状态只有一个权威 owner。

贡献流程​

  1. Fork 仓库并从 main 创建分支。
  2. 在正确的 crate 中实现修改并添加相邻测试。
  3. 运行受影响 crate 的检查，再运行相关 workspace 检查。
  4. 使用 Conventional Commit 风格提交。
  5. 推送分支并创建 Pull Request。
git checkout -b feat/my-feature
cargo check -p <crate-name>
cargo test -p <crate-name>

提交规范​

提交主题使用：

<type>(<scope>): <imperative summary>

示例：

feat(terminal): add search result navigation
fix(transport): handle closed SSH channels
docs: update development setup

常用类型包括 feat、fix、docs、refactor、perf、test 和 chore。常用 scope 包括 terminal、transport、desktop、storage、ui、ai 和 sync。

代码与测试​

cargo check --workspace
cargo test --workspace
cargo fmt --all -- --check
cargo clippy --workspace --all-targets
  • 使用 Rust 2024 idiom、标准 rustfmt 和显式 import。
  • 不要增加 #[path = "..."]、use super::* 或共享 feature prelude。
  • render 路径中不执行数据库、文件系统、网络或其他阻塞操作。
  • 存储、凭据、加密、备份和同步修改需要新数据 round trip 与代表性旧数据测试。
  • 平台相关窗口、PTY、串口、剪贴板和输入行为需在目标系统验证。

国际化与文档​

新增或修改应用 UI 文本时同步更新：

  • crates/nyaterm-desktop/src/i18n/locales/zh-CN.json
  • crates/nyaterm-desktop/src/i18n/locales/en.json

修改 docs-site 时同步维护 docs-site/docs/ 中文源文档和 docs-site/i18n/en/docusaurus-plugin-content-docs/current/ 英文页面，新增页面还要加入 docs-site/sidebars.ts，并运行：

python3 scripts/ci/check_docs_translations.py
pnpm --dir docs-site build

修改第三方依赖​

打了补丁的第三方依赖不在仓库里，而是 github.com/nyakang 下 fork 的 nyaterm 分支上的补丁序列。改动流程见 开发环境搭建 → 修改第三方依赖。

要点：提交到 fork 分支并推送，再在根 Cargo.toml 里 bump revision；补丁按关注点拆分；在提交信息和该分支的 NYATERM.md 里记录原因和验证方式。PR 描述中需注明改动的 fork 分支和 revision。

不要改 temp/。 那里是只读副本，不参与编译，改动既不生效也不报错。

安全与兼容性​

不要提交或记录密码、私钥、OTP、API secret 或未脱敏的终端上下文。持久化修改必须保留现有 table、key、字段名、加密前缀、备份格式和 fallback 行为，除非同时提供经过测试的迁移。

许可证​

贡献代码遵循项目的 Apache License 2.0。