mirror of https://github.com/nyakang/nyaterm.git synced 2026-09-22 08:01:31 +00:00

Files

T

KangandClaude Opus 5 ab02c222cc ci(docs): build the docs site and check translation parity

The docs site was not in any CI path filter, so nothing built it and nothing
compared the two locales. That is how the English pages drifted several
sections behind Chinese and how seven internal screenshot-planning notes stayed
published.

- Add scripts/ci/check_docs_translations.py, covering what a Docusaurus build
  does not: a page existing in only one locale, a heading-count mismatch
  between the two copies, a page no sidebar references, and authoring
  leftovers (screenshot-planning notes, /img/docs/ paths, scripts/demo-*.sh
  references, stray TODO markers). Verified it fails on each of those by
  reintroducing them.
- Add a Documentation site job that runs the script and then builds every
  locale, and add docs-site/** to the workflow path filters.
- Fix docs-site/pnpm-workspace.yaml, whose allowBuilds entries still held the
  placeholder text "set this to true or false". That made every `pnpm install`
  in the site fail with ERR_PNPM_IGNORED_BUILDS, which means the
  `pnpm --dir docs-site build` command our own contributing guide tells people
  to run did not work. Deny the four build scripts explicitly; none is needed
  to build the site.
- Correct the homepage, which still advertised only SSH, local shell, Telnet,
  and serial: the workspace card, the docs card, and the page description now
  name RDP, VNC, and the AI assistant. The three retargeted translate() keys
  are updated in i18n/en/code.json so English does not fall back to Chinese.
- Document the new script in the setup and contributing guides, replacing the
  note that said no translation-completeness check exists.

Verified with `python3 scripts/ci/check_docs_translations.py`,
`pnpm --dir docs-site install --frozen-lockfile`, and
`pnpm --dir docs-site build`, and by confirming the new homepage strings render
in both locales.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

2026-08-22 11:27:47 +08:00

3.8 KiB

Raw Blame History

贡献指南

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

开始之前

阅读仓库根目录的 AGENTS.md 和 CONTRIBUTING.md。
按照开发环境搭建配置 Rust 和平台依赖。
查看 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。

贡献流程

Fork 仓库并从 main 创建分支。
在正确的 crate 中实现修改并添加相邻测试。
运行受影响 crate 的检查，再运行相关 workspace 检查。
使用 Conventional Commit 风格提交。
推送分支并创建 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。

3.8 KiB Raw Blame History Unescape Escape