nex_shift/CONTRIBUTING.md

142 lines
5.7 KiB
Markdown

# Contributing to Shift
Shift is a Tauri 2 desktop application: React/TypeScript renderers talk to a Rust
command layer, with native macOS, Windows and Linux adapters underneath. Changes
should stay local to the behaviour being fixed; the regression ledger in
[`docs/ENGINEERING-NOTES.md`](docs/ENGINEERING-NOTES.md) records paths that must
not be simplified back into earlier failures.
## Prerequisites
- Node.js 22 (the CI baseline) and pnpm 8 or newer. The repository has no
`packageManager` pin, so use an installed pnpm rather than assuming Corepack
selects one.
- Current stable Rust and Cargo; the CI workflow tracks the stable channel.
- macOS: macOS 13 or newer and the Xcode Command Line Tools for the Swift
sidecars.
- Windows: Visual Studio Build Tools with the Desktop development with C++
workload, WebView2, and the Tauri prerequisites. See
[`docs/BUILD_WINDOWS.md`](docs/BUILD_WINDOWS.md).
- Linux: the GTK/WebKit/AppIndicator packages listed in
[`.github/workflows/ci.yml`](.github/workflows/ci.yml), plus `grim`,
`gnome-screenshot`, `wf-recorder` and FFmpeg for the optional capture paths.
## Local setup
```bash
pnpm install
pnpm prepare:ocr
pnpm mac:drag-bridge # macOS only
pnpm tauri dev
```
`pnpm prepare:ocr` refreshes the tracked Tesseract WASM and language assets
under `public/tesseract/`. They are committed so a clean checkout can build and
run OCR offline. Do not delete or replace them with remote downloads.
## Required checks
Run the checks from the repository root unless a command says otherwise:
```bash
pnpm check
pnpm test
pnpm build
cd src-tauri
cargo fmt --check
cargo test --lib
cargo clippy --all-targets -- -D warnings
cd ..
git diff --check
```
The two network-dependent Rust tests are ignored by default:
- `share::tests::two_copies_on_one_machine_discover_each_other` binds the shared
discovery port.
- `update::tests::the_configured_feed_parses_and_downloads` reaches the update
feed.
Run the first explicitly when working on discovery, and the second only with a
feed you are willing to download from:
```bash
cd src-tauri
cargo test share:: -- --ignored --nocapture
SHIFT_UPDATE_URL="<manifest-url>" cargo test --lib update:: -- --ignored
```
## What CI covers
[`.github/workflows/ci.yml`](.github/workflows/ci.yml) defines macOS, Windows and
Linux jobs. They run type checks, TypeScript tests, Rust formatting and Rust
unit tests; macOS also runs Clippy and a universal app build. Nothing in this
repository proves that the current hosting forge has a runner configured.
Link an actual run before describing CI as passing.
## Change rules
- Keep the source file untouched. Every operation writes a new result through
the collision-safe naming helpers.
- Where the interface maps a backend failure, use a stable code such as
`errTextTooLarge` or `share-timeout`; user wording belongs in `src/i18n.ts`.
Add both English and Simplified Chinese. Raw third-party diagnostics may pass
through unchanged.
- Use `messageFrom()` for unknown errors and `tLive()` for listeners that are
registered once and must follow later language changes.
- Preserve protocol compatibility. LAN beacons and transfer headers may gain
defaulted fields, but existing field meanings must not change. Update
manifests are `schema: 1`; reject unsupported schemas instead of guessing.
- Treat downloaded installers and LAN input as untrusted. Do not interpolate
paths into shell or batch text, and do not trust a declared file size without
enforcing it while copying.
- Resource limits belong at the point where bytes are read or decoded, not only
in the UI. The editor currently caps text at 8 MiB, image files at 64 MiB and
decoded images at 40 megapixels; document any new unbounded path or add a
limit.
- Do not edit generated output in `dist/`, `src-tauri/target/`, `artifacts/`, or
generated icons. Change the source and the build script that produces them.
## Documentation changes
User-visible behaviour changes require matching updates in both
[`README.md`](README.md) and [`README.zh-CN.md`](README.zh-CN.md). Architecture
changes belong in [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md); observable
behaviour and limits belong in [`docs/SPECIFICATION.md`](docs/SPECIFICATION.md);
trust-boundary changes belong in [`docs/SECURITY.md`](docs/SECURITY.md).
If a change alters discovery, conversion dependencies, update handoff or macOS
packaging, append the reason, evidence and any commit reference to
`docs/ENGINEERING-NOTES.md` rather than leaving the next contributor to
rediscover it.
## Manual checks
Unit tests cannot prove gesture handling, OS permissions, installer behaviour or
cross-machine discovery. Before a release, complete the relevant matrix:
- macOS: first launch, Screen Recording and Files & Folders permissions, area
and full-screen capture, editor save and copy, drag-to-ring, LAN receive.
- Windows: installer, firewall prompt, drag-to-ring threshold, WebView2 file
drag paths, recording with FFmpeg, LAN receive.
- Linux: build package, `grim` / `gnome-screenshot`, Wayland `wf-recorder`,
X11 FFmpeg fallback, Poppler-dependent paths.
- Updates: install the previous release and run the in-app handoff once on each
shipped platform. On Windows this requires real Windows hardware.
Record which checks were run and which were not. Do not replace an unavailable
hardware check with a compile result.
## Release work
The release process, signing key handling and channel verification are in
[`docs/RELEASE.md`](docs/RELEASE.md). A release key must never enter the
repository, logs or issue attachments. Use `scripts/release-key.py` with the key
outside the working tree.
Do not commit generated artifacts or publish a `releases` branch unless the
task explicitly asks for it.