docs: accessibility statement, contributing guide, code of conduct and templates
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>
This commit is contained in:
1 parent
d016b80014
commit
3e2c5e1a07
5 files changed
+545
No files matched your search
@@ -0,0 +1,66 @@
|
||||
name: Accessibility barrier
|
||||
description: Something in PipDock is hard or impossible to use with a keyboard, a screen reader, high contrast or zoom
|
||||
title: "[A11y]: "
|
||||
labels: ["accessibility", "triage"]
|
||||
body:
|
||||
- type: markdown
|
||||
attributes:
|
||||
value: |
|
||||
Thank you for telling us. You do not need to know the cause, name a WCAG criterion or
|
||||
suggest a fix — what you were trying to do and what happened is a complete report.
|
||||
|
||||
If filling in a form is itself the barrier, write to **accessibility@poli0981.dev**
|
||||
instead. Vui lòng viết bằng English hoặc Tiếng Việt đều được.
|
||||
- type: textarea
|
||||
id: what-happened
|
||||
attributes:
|
||||
label: What were you trying to do, and what happened instead?
|
||||
placeholder: "I tabbed to a package row and could not reach the Remove button."
|
||||
validations:
|
||||
required: true
|
||||
- type: dropdown
|
||||
id: impact
|
||||
attributes:
|
||||
label: How much does it get in your way?
|
||||
description: This decides how soon it is fixed. A barrier that stops you goes into the next release.
|
||||
options:
|
||||
- "It stops me — I cannot do this at all"
|
||||
- "I can do it, but only with real difficulty or a workaround"
|
||||
- "It slows me down or is confusing"
|
||||
- "It is a small annoyance"
|
||||
validations:
|
||||
required: true
|
||||
- type: input
|
||||
id: assistive-tech
|
||||
attributes:
|
||||
label: Assistive technology and version, if any
|
||||
placeholder: "Narrator (Windows 11 24H2) · NVDA 2026.3 · a contrast theme · 200% zoom · keyboard only"
|
||||
- type: dropdown
|
||||
id: where
|
||||
attributes:
|
||||
label: Where in PipDock?
|
||||
options:
|
||||
- "The desktop application"
|
||||
- "The pipdock command line"
|
||||
- "The installer"
|
||||
- "The documentation or this repository"
|
||||
validations:
|
||||
required: true
|
||||
- type: input
|
||||
id: pd-version
|
||||
attributes:
|
||||
label: PipDock version
|
||||
placeholder: "x.y.z — shown under About → This build"
|
||||
validations:
|
||||
required: true
|
||||
- type: input
|
||||
id: os
|
||||
attributes:
|
||||
label: Windows version
|
||||
placeholder: "Windows 11 24H2 (26100.x)"
|
||||
- type: textarea
|
||||
id: steps
|
||||
attributes:
|
||||
label: Steps to reproduce (optional)
|
||||
description: The keys you pressed, or what your screen reader said, in order. A recording is welcome and not required.
|
||||
placeholder: "1. Ctrl+2 … 2. Tab to the first row … 3. …"
|
||||
@@ -0,0 +1,36 @@
|
||||
<!--
|
||||
One pull request is one slice: a single thing, taken deep, with its tests. CONTRIBUTING.md has the
|
||||
details. Delete the sections that do not apply.
|
||||
-->
|
||||
|
||||
## What this changes
|
||||
|
||||
<!-- What a user or a script would notice, and why. Link the issue or the docs/ROADMAP.md entry. -->
|
||||
|
||||
## How it was checked
|
||||
|
||||
<!-- The commands you ran, and what you did in the running app. "Tests pass" is not the whole answer:
|
||||
most defects in this project were found by running it. -->
|
||||
|
||||
- [ ] A test fails without this change and passes with it
|
||||
- [ ] `npm run lint`, `npm run typecheck`, `npm test`
|
||||
- [ ] `cargo fmt --check`, `cargo clippy --workspace --all-targets -- -D warnings`, `cargo test --workspace --locked`
|
||||
|
||||
## If it touches…
|
||||
|
||||
- [ ] **A Rust type that crosses to the UI** — bindings regenerated (`cargo run -p xtask -- bindings`)
|
||||
- [ ] **CLI output** — goldens re-blessed deliberately, and the diff is the change you meant
|
||||
- [ ] **User-visible text** — added to both `ui/src/locales/en` and `ui/src/locales/vi`; nothing phrased in Rust
|
||||
- [ ] **A new error code** — every place `CLAUDE.md` lists, both `errors.json` included
|
||||
- [ ] **Behaviour a user reads about** — `docs/` updated, and `legal/` checked separately
|
||||
- [ ] **Something a user would notice** — an entry in `changelog/`
|
||||
|
||||
## Accessibility (for any change to the interface)
|
||||
|
||||
- [ ] Everything new can be reached and operated with the keyboard alone
|
||||
- [ ] Focus is visible, and goes somewhere sensible when the screen changes or a dialog closes
|
||||
- [ ] Controls that show only a symbol have an accessible name; inputs have labels
|
||||
- [ ] Nothing is said by colour alone, and a destructive button carries `data-destructive`
|
||||
- [ ] Checked once with a screen reader, or said here that it was not
|
||||
|
||||
<!-- ACCESSIBILITY.md is the statement these keep true. -->
|
||||
@@ -0,0 +1,198 @@
|
||||
# Accessibility
|
||||
|
||||
PipDock is meant to be usable by someone who uses a keyboard and no mouse, by someone who uses a
|
||||
screen reader, and by someone who needs high contrast or larger text. This document says what that
|
||||
means in practice, what has actually been tested and what has not, what is known not to work, and
|
||||
how to tell us when something gets in your way.
|
||||
|
||||
**If you have hit a barrier, skip to [Reporting a barrier](#reporting-a-barrier).** You do not need
|
||||
a GitHub account, and you do not need to diagnose the problem first.
|
||||
|
||||
## What we are working toward
|
||||
|
||||
The target is [WCAG 2.2](https://www.w3.org/TR/WCAG22/) Level AA, applied to a desktop application
|
||||
and a command-line tool.
|
||||
|
||||
**This is a target, not a conformance claim.** PipDock has not been audited by anyone independent,
|
||||
and the sections below list things that are known to fall short. What it has is a set of rules the
|
||||
code is held to, tests that hold some of them, and one person's hands-on testing.
|
||||
|
||||
The priorities, in the order they are defended:
|
||||
|
||||
1. **Everything works from the keyboard.** No function needs a pointer.
|
||||
2. **A screen reader is told what is on screen and what just changed.**
|
||||
3. **Nothing is said by colour alone**, and text has enough contrast to read.
|
||||
4. **The system's own settings are respected** — contrast themes, reduced motion, language.
|
||||
|
||||
## What is supported
|
||||
|
||||
### Keyboard
|
||||
|
||||
Every control is reachable and operable from the keyboard. The focus ring is a 2 px outline and is
|
||||
never removed.
|
||||
|
||||
| Keys | What they do |
|
||||
|---|---|
|
||||
| `Tab` / `Shift+Tab` | Move between controls. In the package table each row is one stop |
|
||||
| `Ctrl+1` … `Ctrl+9` | Go to a sidebar tab, by key position (works on layouts where digits need Shift) |
|
||||
| `Ctrl+K` | Open the command palette; type to filter, `↑` `↓` to move, `Enter` to run, `Esc` to close |
|
||||
| `/` | Go to Search and put the cursor in its field |
|
||||
| `Space` | On a package row: select or deselect it |
|
||||
| `Ctrl+A` | In the package table: select every row the screen is showing |
|
||||
| `Enter` | On a package row: pin or unpin it. Never removes anything |
|
||||
| `←` `→` | On a package row: move through its buttons (dependencies, pin, remove) |
|
||||
| `←` `→` `Home` `End` | In Code Health: move between the tool tabs |
|
||||
| `←` `→` `↑` `↓` | In a version conflict: move between *Keep compatible*, *Skip* and *Force latest*. Nothing is chosen until you press `Space` or `Enter` |
|
||||
| `Esc` | Close a dialog, the palette or the console drawer; inside a package row, return to the row |
|
||||
| `Ctrl` `+` / `Ctrl` `-` / `Ctrl+0` | Zoom in, zoom out, reset |
|
||||
|
||||
When the screen changes — a new tab, a plan's preview, its summary, the dependency view — focus
|
||||
moves to the new screen's heading. When a dialog, the palette or the console drawer closes, focus
|
||||
returns to what opened it. Every confirmation that removes, forces or rewrites something opens with
|
||||
focus on **Cancel**.
|
||||
|
||||
The full map and the reasoning behind it are in [`docs/UI-SPEC.md`](docs/UI-SPEC.md) §8.
|
||||
|
||||
### Screen readers
|
||||
|
||||
- Each screen has landmarks (header, navigation, main, footer) and one top-level heading.
|
||||
- The package table is exposed as a grid with column headers, a row count and selection state.
|
||||
- Buttons that show only a symbol have names. Status chips say what they mean in text.
|
||||
- Dialogs are named by their heading and described by their body.
|
||||
- A run announces its progress ("3 of 15 complete") once, not once per output line. Search
|
||||
announces that it is searching, how many results came back, and when nothing matched.
|
||||
- Error messages are announced when they appear, and carry a code (`PD-XXX-000`) you can quote.
|
||||
- The interface is in English and Vietnamese, and the document language follows the one in use.
|
||||
|
||||
### High contrast
|
||||
|
||||
Under a Windows contrast theme (forced colours), every colour in the interface is replaced by the
|
||||
system's own. Because that removes every tint, the things a tint used to say are drawn another way:
|
||||
destructive buttons get a heavier border, and the selected row, the selected search result and the
|
||||
current sidebar tab get an outline.
|
||||
|
||||
### Colour, contrast and motion
|
||||
|
||||
- Text and status chips are checked against their backgrounds for at least 4.5:1 by a test that
|
||||
runs on every change. Status is always a word or a symbol as well as a colour.
|
||||
- There is no animation in the interface. `prefers-reduced-motion` is honoured for anything that
|
||||
is ever added.
|
||||
|
||||
### The command line
|
||||
|
||||
`pipdock` prints plain text with no colour, no spinners and no lines that rewrite themselves. Every
|
||||
command takes `--json` for one machine-readable document on standard output and `--quiet` to drop
|
||||
progress; prompts, progress and warnings go to standard error; failures use documented exit codes.
|
||||
Most of what the GUI does is available there — [`docs/CLI-GUIDE.md`](docs/CLI-GUIDE.md) lists the
|
||||
few things that are not — so it is often a workable alternative while a GUI barrier is being fixed.
|
||||
|
||||
## What has been tested, and how
|
||||
|
||||
Honesty about this matters more than a long list.
|
||||
|
||||
| What | How | By whom, when |
|
||||
|---|---|---|
|
||||
| Every main flow with the mouse unplugged | By hand, on the installed 1.4.0 build, Windows 11 | The maintainer, November 2026. No blocking problem found |
|
||||
| The same flows with Narrator | By hand, on the installed 1.4.0 build, Windows 11 | The maintainer, November 2026. No blocking problem found |
|
||||
| Structure: roles, names, required parts | [axe-core](https://github.com/dequelabs/axe-core) over every screen, on every change | Automated, from 1.5.0 |
|
||||
| Keyboard behaviour and where focus goes | Unit tests, on every change | Automated |
|
||||
| Text contrast | Computed from the design tokens, on every change | Automated |
|
||||
| High contrast, zoom, the accessibility tree | In the running application, with forced colours emulated | During the 1.5.0 release |
|
||||
|
||||
**Not tested, and said so rather than implied:**
|
||||
|
||||
- **Narrator has not been run again on 1.5.0.** That release changed what a screen reader hears in
|
||||
several places (see the [changelog](changelog/1.x.md)). Those changes were checked against the
|
||||
accessibility tree, which says what is exposed — not against speech, which is what you hear.
|
||||
- **NVDA and JAWS** have not been used with PipDock at all. Reports from people who use them are
|
||||
especially welcome.
|
||||
- **Each Windows contrast theme by hand.** Forced colours were emulated; the four built-in themes
|
||||
were not each switched on.
|
||||
- **Windows 10.** PipDock supports it, and the testing above was on Windows 11.
|
||||
- **The installers.** The setup program and the MSI are produced by NSIS and WiX, and their
|
||||
accessibility is whatever those tools provide. It has not been assessed.
|
||||
- Voice control, switch access and screen magnifiers.
|
||||
|
||||
## Known limitations
|
||||
|
||||
These are real, they are tracked in [`docs/ROADMAP.md`](docs/ROADMAP.md) under *Audit backlog*, and
|
||||
where there is a workaround it is given.
|
||||
|
||||
- **One theme.** The interface is dark, with no light theme. A Windows contrast theme, light ones
|
||||
included, replaces every colour.
|
||||
- **The package table is one tab stop per row.** There is no `↑` / `↓` between rows yet, so
|
||||
passing a long table by `Tab` is slow. *Workaround:* `Ctrl+1` … `Ctrl+9` jump past it, and the
|
||||
Updates tab lists only what is outdated.
|
||||
- **Only the rows on screen exist.** The table draws about 25 rows at a time, so a screen reader's
|
||||
own "list all rows" finds only those. The row count and each row's position are exposed.
|
||||
- **Live output is not read line by line.** The console drawer shows an engine's output as it
|
||||
arrives and deliberately does not announce it; progress is announced instead. The text is there
|
||||
to read at your own pace.
|
||||
- **Some announcements are unverified.** A few status messages appear together with the part of
|
||||
the screen that carries them, and several errors can appear at once after a failed batch.
|
||||
Whether a screen reader says them, and in what order, has not been confirmed on 1.5.0.
|
||||
- **A few failures say nothing.** If saving a report, copying to the clipboard or opening a file
|
||||
picker fails, the screen does not change. Nothing is lost, but nothing tells you either.
|
||||
- **Why a control is disabled is sometimes only in a tooltip**, which a keyboard cannot reach
|
||||
because a disabled control cannot be focused.
|
||||
- **Long paths and package names are cut off** rather than wrapped in a few places, which gets
|
||||
worse with zoom.
|
||||
- **Dates and sizes are not formatted for the interface language.**
|
||||
- **`Ctrl+K` is matched by the letter the layout types**, unlike the digit shortcuts, so it moves
|
||||
on a layout where K is elsewhere.
|
||||
- **The legal documents open in your browser**, on GitHub, rather than inside the application.
|
||||
|
||||
## Reporting a barrier
|
||||
|
||||
Either of these reaches the same person:
|
||||
|
||||
- **[Open an accessibility issue](https://github.com/poli0981/pipdock/issues/new?template=accessibility.yml)**
|
||||
on GitHub, or
|
||||
- write to **[accessibility@poli0981.dev](mailto:accessibility@poli0981.dev)** — no account needed.
|
||||
|
||||
Write in English or Vietnamese — tiếng Việt cũng được. It helps to include:
|
||||
|
||||
- what you were trying to do, and what happened instead;
|
||||
- the PipDock version (**About → This build**) and your Windows version;
|
||||
- the assistive technology you use and its version, if any — Narrator, NVDA, a contrast theme,
|
||||
zoom level, keyboard only;
|
||||
- whether it stops you completely or slows you down.
|
||||
|
||||
You do not have to work out the cause, name a WCAG criterion or propose a fix. "I could not get
|
||||
past the first screen" is a complete report.
|
||||
|
||||
### What happens next
|
||||
|
||||
- **You get an answer within 7 days**, the same commitment as for security reports.
|
||||
- A barrier that stops someone using PipDock is treated as a bug of the highest priority and goes
|
||||
into the next release. Others are scheduled like any other defect and recorded in the roadmap.
|
||||
- If there is a workaround — often the command line — you will be told what it is straight away.
|
||||
- You will be told when a fix ships, and asked whether it worked for you.
|
||||
|
||||
**There is no fixed deadline for a fix.** PipDock is made by one person, and a promised date that
|
||||
slips is worse than none. What is promised is the answer, the priority, and that a report is never
|
||||
closed as "works for me" without being tried the way you described it.
|
||||
|
||||
## For contributors
|
||||
|
||||
A change to the interface is not finished until it works without a mouse.
|
||||
[`CONTRIBUTING.md`](CONTRIBUTING.md) has the checklist, and the pull request template repeats it.
|
||||
In short: reach it and operate it by keyboard, keep the focus ring, put focus somewhere sensible
|
||||
when the screen changes, name anything that shows only a symbol, never say something by colour
|
||||
alone, mark a destructive button `data-destructive`, add copy in both languages, and keep
|
||||
`npm test` green — it runs axe over every screen.
|
||||
|
||||
## Ownership
|
||||
|
||||
Accessibility reports go to the maintainer, [@poli0981](https://github.com/poli0981), who triages
|
||||
them, keeps the list of known limitations above true, and updates this document with each release
|
||||
that changes it.
|
||||
|
||||
Last reviewed: 2026-11-10, for PipDock 1.5.0.
|
||||
|
||||
---
|
||||
|
||||
The structure of this document follows the
|
||||
[Accessibility Toolkit's `ACCESSIBILITY.md`](https://github.com/open-source-accessibility/accessibility-toolkit/blob/main/ACCESSIBILITY.md)
|
||||
(MIT), following GitHub's
|
||||
[guide to accessibility in open source](https://opensource.guide/accessibility-best-practices-for-your-project/).
|
||||
@@ -0,0 +1,84 @@
|
||||
# Contributor Covenant Code of Conduct
|
||||
|
||||
## Our Pledge
|
||||
|
||||
We as members, contributors, and leaders pledge to make participation in our community a harassment-free experience for everyone, regardless of age, body size, visible or invisible disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, caste, color, religion, or sexual identity and orientation.
|
||||
|
||||
We pledge to act and interact in ways that contribute to an open, welcoming, diverse, inclusive, and healthy community.
|
||||
|
||||
## Our Standards
|
||||
|
||||
Examples of behavior that contributes to a positive environment for our community include:
|
||||
|
||||
* Demonstrating empathy and kindness toward other people
|
||||
* Being respectful of differing opinions, viewpoints, and experiences
|
||||
* Giving and gracefully accepting constructive feedback
|
||||
* Accepting responsibility and apologizing to those affected by our mistakes, and learning from the experience
|
||||
* Focusing on what is best not just for us as individuals, but for the overall community
|
||||
|
||||
Examples of unacceptable behavior include:
|
||||
|
||||
* The use of sexualized language or imagery, and sexual attention or advances of any kind
|
||||
* Trolling, insulting or derogatory comments, and personal or political attacks
|
||||
* Public or private harassment
|
||||
* Publishing others' private information, such as a physical or email address, without their explicit permission
|
||||
* Other conduct which could reasonably be considered inappropriate in a professional setting
|
||||
|
||||
## Enforcement Responsibilities
|
||||
|
||||
Community leaders are responsible for clarifying and enforcing our standards of acceptable behavior and will take appropriate and fair corrective action in response to any behavior that they deem inappropriate, threatening, offensive, or harmful.
|
||||
|
||||
Community leaders have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct, and will communicate reasons for moderation decisions when appropriate.
|
||||
|
||||
## Scope
|
||||
|
||||
This Code of Conduct applies within all community spaces, and also applies when an individual is officially representing the community in public spaces. Examples of representing our community include using an official e-mail address, posting via an official social media account, or acting as an appointed representative at an online or offline event.
|
||||
|
||||
## Enforcement
|
||||
|
||||
Instances of abusive, harassing, or otherwise unacceptable behavior may be reported to the community leaders responsible for enforcement at [contact@poli0981.dev](mailto:contact@poli0981.dev). All complaints will be reviewed and investigated promptly and fairly.
|
||||
|
||||
All community leaders are obligated to respect the privacy and security of the reporter of any incident.
|
||||
|
||||
## Enforcement Guidelines
|
||||
|
||||
Community leaders will follow these Community Impact Guidelines in determining the consequences for any action they deem in violation of this Code of Conduct:
|
||||
|
||||
### 1. Correction
|
||||
|
||||
**Community Impact**: Use of inappropriate language or other behavior deemed unprofessional or unwelcome in the community.
|
||||
|
||||
**Consequence**: A private, written warning from community leaders, providing clarity around the nature of the violation and an explanation of why the behavior was inappropriate. A public apology may be requested.
|
||||
|
||||
### 2. Warning
|
||||
|
||||
**Community Impact**: A violation through a single incident or series of actions.
|
||||
|
||||
**Consequence**: A warning with consequences for continued behavior. No interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, for a specified period of time. This includes avoiding interactions in community spaces as well as external channels like social media. Violating these terms may lead to a temporary or permanent ban.
|
||||
|
||||
### 3. Temporary Ban
|
||||
|
||||
**Community Impact**: A serious violation of community standards, including sustained inappropriate behavior.
|
||||
|
||||
**Consequence**: A temporary ban from any sort of interaction or public communication with the community for a specified period of time. No public or private interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, is allowed during this period. Violating these terms may lead to a permanent ban.
|
||||
|
||||
### 4. Permanent Ban
|
||||
|
||||
**Community Impact**: Demonstrating a pattern of violation of community standards, including sustained inappropriate behavior, harassment of an individual, or aggression toward or disparagement of classes of individuals.
|
||||
|
||||
**Consequence**: A permanent ban from any sort of public interaction within the community.
|
||||
|
||||
## Attribution
|
||||
|
||||
This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 2.1, available at [https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1].
|
||||
|
||||
Community Impact Guidelines were inspired by [Mozilla's code of conduct enforcement ladder][Mozilla CoC].
|
||||
|
||||
For answers to common questions about this code of conduct, see the FAQ at [https://www.contributor-covenant.org/faq][FAQ]. Translations are available at [https://www.contributor-covenant.org/translations][translations].
|
||||
|
||||
[homepage]: https://www.contributor-covenant.org
|
||||
[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html
|
||||
[Mozilla CoC]: https://github.com/mozilla/diversity
|
||||
[FAQ]: https://www.contributor-covenant.org/faq
|
||||
[translations]: https://www.contributor-covenant.org/translations
|
||||
|
||||
+161
@@ -0,0 +1,161 @@
|
||||
# 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](CODE_OF_CONDUCT.md).
|
||||
|
||||
## Before you write code
|
||||
|
||||
- **A bug** — [open an issue](https://github.com/poli0981/pipdock/issues/new/choose). 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](ACCESSIBILITY.md). That report does not need a diagnosis.
|
||||
- **A security problem** — do not open an issue; follow the [security policy](.github/SECURITY.md).
|
||||
- **A question or an idea** — [Discussions](https://github.com/poli0981/pipdock/discussions).
|
||||
- **A feature** — please ask first. The design is written down in `docs/`, the feature list and its
|
||||
non-goals are in [`docs/PRD.md`](docs/PRD.md), and what is planned and why is in
|
||||
[`docs/ROADMAP.md`](docs/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](https://tauri.app/start/prerequisites/) |
|
||||
|
||||
```bash
|
||||
npm ci
|
||||
```
|
||||
|
||||
```bash
|
||||
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
|
||||
|
||||
```bash
|
||||
npm run lint
|
||||
```
|
||||
|
||||
```bash
|
||||
npm run typecheck
|
||||
```
|
||||
|
||||
```bash
|
||||
npm test
|
||||
```
|
||||
|
||||
```bash
|
||||
cargo fmt --all -- --check
|
||||
```
|
||||
|
||||
```bash
|
||||
cargo clippy --workspace --all-targets --locked -- -D warnings
|
||||
```
|
||||
|
||||
```bash
|
||||
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](.github/PULL_REQUEST_TEMPLATE.md) 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](https://www.conventionalcommits.org/)** —
|
||||
`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/`](changelog/README.md), 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:
|
||||
|
||||
```bash
|
||||
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`](docs/DATA-FLOW.md) §9 and [`docs/SECURITY.md`](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](https://github.com/dequelabs/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](ACCESSIBILITY.md) is the statement these keep true, and
|
||||
[`docs/UI-SPEC.md`](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`](docs/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](LICENSE). 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`](docs/AI-DISCLOSURE.md) says how.
|
||||
Reference in new issue
Block a user