Files
pipdock/CONTRIBUTING.md
poli0981andClaude Opus 5.5 39be719b22 docs: maintenance mode — what is taken, what is not planned, and why
README carries the status in both languages, CONTRIBUTING a 'Scope in
maintenance mode' section the triage bot links to, and ROADMAP a section
recording the decision: dependency, security, major-upgrade, defect and
wording work is taken; P1-7, X19, the engine caches and P2 are not
planned, each with its reason. The Audit backlog is the maintenance
backlog.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-21 23:22:12 +07:00

9.5 KiB

Contributing to PipDock

Thank you for wanting to help. PipDock is made by one person, so the most useful contributions are the ones that arrive easy to say yes to: a bug report that reproduces, or a pull request that does one thing and proves it.

By taking part you agree to the Code of Conduct.

Scope in maintenance mode

Since 1.6.0 (2026-11), PipDock is maintained rather than developed. It does what it was designed to do — the last missing core feature, adding an interpreter by path, shipped in 1.6.0 — and from here the work is keeping it correct, safe and current. What that takes in:

  • Regular dependency updates — Rust crates, npm packages, GitHub Actions and the Code Health tool pins, the way Dependabot proposes them.
  • Security fixes — a dependency with a High or Critical advisory, or a serious security problem in a runtime or toolchain PipDock is built with (Node, Rust, WebView2), fixed promptly and released when it reaches the shipped program.
  • Major language, runtime and framework upgrades — Node 26 to 28, TypeScript 6 to 7, a Rust edition, Tauri 2 to 3 — when they arrive and are stable.
  • Bugs, UI/UX defects and accessibility barriers — anything that does not work as the docs describe, gets in someone's way, or cannot be used with a keyboard, a screen reader or high contrast.
  • Wording and translation — English or Vietnamese text that is wrong, misspelt in a way that changes the meaning, misleading, or does not read the way people actually speak. There is an issue form for it.

New features are not taken, as issues or as pull requests. One that asks for a feature — titled as a feature request, a feat: pull request, or labelled enhancement — is labelled out-of-scope and closed automatically, with this section linked. That is not a judgement of the idea. If you believe something is truly necessary — it fixes data loss, a security hole, or makes the program unusable for someone without it — make the case in Discussions → Ideas; the maintainer can keep an item open with the policy-exception label.

What is planned, and what was deliberately not built, is in docs/ROADMAP.md under Maintenance mode.

Before you write code

  • A bug — open an issue. The in-app Report bug button fills most of the form in for you.
  • Something that gets in your way as a keyboard, screen-reader or high-contrast user — see ACCESSIBILITY.md. That report does not need a diagnosis.
  • A security problem — do not open an issue; follow the security policy.
  • Wrong or misleading text, in either language — the Wording or translation problem form.
  • A question — Discussions.
  • A feature — not during maintenance; see above. The design is written down in docs/, and a fix that contradicts it will be asked to change the docs first, which is a conversation better had before the code.

Setting up

PipDock is a Windows application: a Rust core, a Tauri 2 shell and a React 19 frontend.

You need Version
Windows 10 or 11, with the WebView2 runtime (Windows 11 has it)
Rust the toolchain in rust-toolchain.toml; rustup installs it on first use
Node.js the major in .nvmrc
Python 3.10 or newer, for the tests that drive a real pip
Build tools the MSVC C++ build tools, as Tauri requires
npm ci
npm run tauri dev

package.json sits at the repository root although the frontend lives in ui/; that is deliberate and Vite is configured for it.

The checks, which are the ones CI runs

npm run lint
npm run typecheck
npm test
cargo fmt --all -- --check
cargo clippy --workspace --all-targets --locked -- -D warnings
cargo test --workspace --locked
node scripts/check-licenses.mjs

A pull request needs eight checks green before it can merge — fmt · clippy · test, cargo audit, cargo deny, lint · typecheck · test · build, npm audit, npm licences, tauri lockstep and CodeQL for JavaScript/TypeScript. Several more run and are read before merging (CodeQL for Rust and Actions, the real-engine integration tests, SonarQube Cloud, Qodana). New code is expected to be covered by tests; the SonarQube gate asks for 80 % on new lines. A new dependency the app ships must be under a licence deny.toml allows — the two licence checks fail otherwise, and widening the list is a licensing decision, not a CI fix.

What a pull request should look like

One pull request, one thing, taken all the way. Not several shallow changes. The template is a checklist of the rest; the parts that surprise people are below.

  • A test that fails first. Write the test, watch it fail for the reason you expect, then make the change. A test that has never failed has not been shown to test anything.
  • Run it. Nearly every unplanned defect in this project was found by running the application or the CLI against a real environment, not by a passing suite. Say in the pull request what you ran.
  • Commit subjects follow Conventional Commits — fix:, feat:, docs:, test:, build(deps):, ci:. Nothing is generated from them; they are for the person reading the log.
  • main has linear history, so pull requests are squashed or rebased, never merge-committed.
  • If a user would notice, add a changelog entry in changelog/, written for that user. Internals belong in the pull request and in docs/ROADMAP.md.

Things that will fail CI if you forget them

  • Rust types that cross to the UI are generated, never hand-copied. After changing one:

    cargo run -p xtask -- bindings
    

    cargo test fails while ui/src/ipc/generated.ts is stale, and names that command.

  • The CLI's output is a contract. crates/pipdock-cli/tests/golden.rs holds a snapshot of every command. A diff there is a real behaviour change: re-bless it because you meant it, never to make the suite green.

  • Every piece of user-visible text lives in both languages — ui/src/locales/en and ui/src/locales/vi. A string literal in JSX is a lint error, and a key missing from either language fails i18n.test.ts. Rust emits codes and data; it never phrases a sentence.

  • Never rewrite a file under tests/fixtures/ with a text-mode tool. They are byte-exact captures of engine output, line endings included.

The rules that are not negotiable

These are what make PipDock safe to point at an environment someone depends on. A change that weakens one will not be merged, however useful it is otherwise.

  1. Nothing mutates an environment without a plan the user accepted and a snapshot that was written. If the snapshot fails, nothing runs.
  2. Subprocesses are started with argument arrays, never through a shell, and package names and versions are validated before they reach one.
  3. PipDock does not resolve dependencies. pip or uv resolves; PipDock explains.
  4. --break-system-packages is never passed unless the user turned the override on.
  5. One failed package never aborts a batch, and every failure carries exactly one catalog code.

docs/DATA-FLOW.md §9 and docs/SECURITY.md are the full statements.

Accessibility

A change to the interface is not done until it works without a mouse. Before you open the pull request:

  • reach and operate everything new with the keyboard alone;
  • check that focus is visible, and that it lands somewhere sensible when the screen changes or a dialog closes — never on nothing;
  • give any control that shows only a symbol an accessible name, and every input a label;
  • do not say anything by colour alone, and put data-destructive on a button that removes, forces or rewrites, so high contrast can still tell it from Cancel;
  • keep npm test green: it runs axe-core over every screen. axe checks structure; it cannot tell you what a screen reader says, so try one if you can — Narrator is Ctrl+Win+Enter — and say in the pull request if you could not.

ACCESSIBILITY.md is the statement these keep true, and docs/UI-SPEC.md §8 is the keyboard map.

Where things are

Path What is there
crates/pipdock-core Everything that touches an environment: engines, plans, snapshots, the error catalog
crates/pipdock-cli The pipdock command line, and its golden tests
src-tauri The desktop shell and the IPC commands
ui/src The React frontend; nothing in it calls Tauri's invoke directly, only the wrappers in ui/src/ipc
docs/ The design: read ARCHITECTURE.md before a structural change
legal/ What a user agrees to. Edits here re-show the first-run screen once, by design

Licence

PipDock is GPL-3.0-only. By contributing you agree that your contribution is licensed under the same terms. Parts of PipDock were written with an AI assistant under human review; docs/AI-DISCLOSURE.md says how.