GitHub's community profile listed five things missing, and the ops repository supplies no defaults despite its description, so they are added here. ACCESSIBILITY.md is at the root, where GitHub looks and where the README can link it. It follows the Accessibility Toolkit's structure, rewritten for a Windows desktop application and a CLI: the target (WCAG 2.2 AA, as a target and not a conformance claim), what is supported, a table of what was tested and by whom, what was not tested, the known limitations, and how to report a barrier without a GitHub account. It commits to an answer within seven days and to no fix date, because one person cannot honestly promise one. CONTRIBUTING.md states the rules a contributor actually meets: the checks CI runs, generated bindings, goldens, both locales, and the invariants that are not negotiable. CODE_OF_CONDUCT.md is Contributor Covenant 2.1, unmodified apart from the contact address. The pull request template carries an accessibility checklist, and accessibility.yml is an issue form that asks for impact rather than for a diagnosis. bug_report.yml keeps its name: the in-app Report bug link is built from it. Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
7.3 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.
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.
- A question or an idea — Discussions.
- A feature — please ask first. The design is written down in
docs/, the feature list and its non-goals are indocs/PRD.md, and what is planned and why is indocs/ROADMAP.md. A pull request that contradicts those will be asked to change them first, and that 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
A pull request needs five checks green before it can merge — fmt · clippy · test, cargo audit,
lint · typecheck · test · build, npm audit and CodeQL for JavaScript/TypeScript. Several more
run and are read before merging (cargo deny, the Tauri version lockstep, CodeQL for Rust and
Actions, the real-engine integration tests, SonarQube Cloud). New code is expected to be covered by
tests; the SonarQube gate asks for 80 % on new lines.
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. mainhas 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 indocs/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 -- bindingscargo testfails whileui/src/ipc/generated.tsis stale, and names that command. -
The CLI's output is a contract.
crates/pipdock-cli/tests/golden.rsholds 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/enandui/src/locales/vi. A string literal in JSX is a lint error, and a key missing from either language failsi18n.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.
- Nothing mutates an environment without a plan the user accepted and a snapshot that was written. If the snapshot fails, nothing runs.
- Subprocesses are started with argument arrays, never through a shell, and package names and versions are validated before they reach one.
- PipDock does not resolve dependencies. pip or uv resolves; PipDock explains.
--break-system-packagesis never passed unless the user turned the override on.- 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-destructiveon a button that removes, forces or rewrites, so high contrast can still tell it from Cancel; - keep
npm testgreen: 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 isCtrl+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.