mirror of https://github.com/nyakang/nyaterm.git synced 2026-11-15 08:08:08 +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

4.3 KiB

Raw Blame History

Contributing

Thank you for your interest in contributing to NyaTerm.

Before you start

Read AGENTS.md and CONTRIBUTING.md at the repository root.
Follow Development Setup to configure Rust and platform dependencies.
Check Issues for the expected behavior and current work.

Choose the owning crate

Pure models, parsing, compatibility formats, and policies belong in nyaterm-core.
Database execution and compatibility readers belong in nyaterm-store.
PTY, SSH, SFTP, Telnet, Serial, tunnel, and transfer runtimes belong in nyaterm-transport.
Terminal state and snapshots belong in nyaterm-terminal; GPUI terminal painting belongs in nyaterm-terminal-gpui.
GPUI state, views, and background coordination belong in nyaterm-desktop.
Shared GPUI controls and theme integration belong in nyaterm-ui.
RDP/VNC session management, input models, and IPC contracts belong in nyaterm-remote-desktop; protocol decoders belong only in nyaterm-rdp-helper and nyaterm-vnc-helper.

Cross-crate changes keep adapters small and explicit, with one authoritative owner for each value.

Contribution workflow

Fork the repository and create a branch from main.
Implement the change in the owning crate and add adjacent tests.
Run checks for the affected crate, then the relevant workspace checks.
Commit with a Conventional Commit-style subject.
Push the branch and open a Pull Request.

git checkout -b feat/my-feature
cargo check -p <crate-name>
cargo test -p <crate-name>

Commit convention

Use this subject format:

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

Examples:

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

Common types include feat, fix, docs, refactor, perf, test, and chore. Common scopes include terminal, transport, desktop, storage, ui, ai, and sync.

Code and tests

cargo check --workspace
cargo test --workspace
cargo fmt --all -- --check
cargo clippy --workspace --all-targets

Use Rust 2024 idioms, standard rustfmt formatting, and explicit imports.
Do not add #[path = "..."], use super::*, or a shared feature prelude.
Do not perform database, filesystem, network, or other blocking work in render paths.
Storage, credential, encryption, backup, and sync changes include new-data round trips and representative legacy-data tests.
Platform-specific window, PTY, Serial, clipboard, and input behavior is verified on the target operating system.

Internationalization and documentation

When adding or changing application UI text, update both:

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

For docs-site changes, keep the Chinese source under docs-site/docs/ and the English pages under docs-site/i18n/en/docusaurus-plugin-content-docs/current/ in sync, add any new page to docs-site/sidebars.ts, then run:

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

Changing third-party dependencies

The third-party dependencies NyaTerm patches are not in this repository. Each is a patch series on a fork under github.com/nyakang on branch nyaterm. The workflow is documented in Development Setup → Changing third-party dependencies.

In short: commit to the fork branch and push, then bump the pinned revision in the root Cargo.toml; keep the patch series split by concern; record the reason and the validation performed on the patch commit and in that branch's NYATERM.md. Note the fork branch and revision in your PR description.

Do not edit temp/. Those are read-only copies that are never compiled — editing them has no effect and produces no error.

Security and compatibility

Never commit or log passwords, private keys, OTP values, API secrets, or unredacted terminal context. Persistence changes preserve existing tables, keys, field names, encryption prefixes, backup formats, and fallback behavior unless they include a tested migration.

License

Contributions are licensed under the project's Apache License 2.0.

4.3 KiB Raw Blame History