proton-drive-linux/CONTRIBUTING.md

Contributing

Thanks for taking the time. This is an unofficial Proton Drive client that people trust with real files, so the bar for changes that touch the filesystem, the sync engine, or the database is deliberately high — everything else is ordinary Rust review.

Before you start

• Read AGENTS.md for repository conventions, docs/DEVELOPMENT.md for building, running and debugging from source, and docs/ARCHITECTURE.md for how the daemon, front ends, and SDK fit together. docs/README.md indexes the rest.
• Check docs/BUGS.md — it is the authoritative issue ledger, and your problem may already be tracked there with context.
• For anything larger than a fix, open an issue first so the design can be discussed before you spend the time.

Development setup

git clone https://github.com/narrrl/proton-drive-linux.git
cd proton-drive-linux
cargo build --workspace

GUI and FUSE targets need the GTK4, libadwaita, WebKitGTK 6, libsecret, D-Bus, and FUSE3 development packages listed in docs/INSTALL.md. Minimum supported Rust version is 1.96. docs/DEVELOPMENT.md explains how to run your build next to, or instead of, the installed service.

Quality gates

CI runs exactly these, and they must pass with zero warnings:

cargo fmt --all -- --check
cargo clippy --workspace --all-targets -- -D warnings
cargo test --workspace --locked
scripts/fuse-acceptance.sh --offline-only

Changes to the FUSE layer, sync, or the queue should also pass the simulation runs and be exercised against a real mount before review — see docs/TESTING.md. Live runs are destructive: use a dedicated test account, never one holding data you cannot lose.

Making changes

• Keep shared logic in pdfs-core. The CLI and GUI never touch the database or the network; they speak the control protocol to the daemon.
• The SQLite schema is forward-only. Never edit a shipped migration — add a new one and bump SCHEMA_VERSION in crates/pdfs-core/src/db/migrations.rs.
• Typed errors and ? over panics on runtime paths. Blocking filesystem, keyring, or control-socket work stays off GTK's main thread.
• staging/ and recovery/ may hold the only copy of user data. Nothing may clear or purge them opportunistically.
• The GUI is fully translated. Wrap every user-visible string in the helpers from crates/pdfs-gui/src/i18n.rs, run po/update.sh, and translate the new entries in every catalog in po/LINGUAS in the same change. See docs/TRANSLATING.md. The CLI and daemon messages stay in English.
• Document what users see. A new command, setting or behaviour belongs in the matching page under docs/ (user guide, CLI reference or configuration) and in the [Unreleased] section of docs/CHANGELOG.md.

Commits and pull requests

Commits follow scoped Conventional Commits, e.g. fix(fuse,core): keep truncate composable with queued revisions.

A pull request should state:

• the user-visible effect and which crates it touches,
• the docs/BUGS.md entries it fixes or affects,
• the commands you ran to verify it,
• screenshots for GTK changes,
• and, explicitly, any migration, recovery, data-loss, or packaging implications.

Security

Do not open a public issue for a vulnerability — see SECURITY.md.