xdrop/CONTRIBUTING.md

Contributing to Xdrop

Thank you for helping improve Xdrop.

This repository follows the guidance from the Open Source Guides: we try to be explicit about scope, expectations, and how to participate so contributors do not waste time on changes that are unlikely to land.

Project focus

Xdrop is focused on open source end-to-end encrypted file transfer for humans and agents, keeping plaintext file names, contents, and keys off the server.

Changes are most likely to be accepted when they improve one or more of these areas:

• privacy or security of the transfer flow
• reliability of uploads, downloads, expiry, or cleanup
• accessibility, usability, or performance of the current product surface
• test coverage, documentation, or developer experience
• operational hardening of the existing React + Go + Docker stack

Changes are less likely to be accepted if they significantly broaden the project into unrelated product areas, add accounts/social features, or increase complexity without a clear privacy or usability win.

Before you start

• Read README.md for the current project status and local setup.
• Follow MESSAGING.md when you touch README copy, homepage copy, SEO text, or other product-facing messaging.
• Search existing issues and pull requests before opening a new one.
• For substantial features, architecture changes, or API contract changes, open an issue first.
• For vulnerabilities or sensitive security concerns, follow SECURITY.md instead of filing a public issue.
• Keep general questions and troubleshooting in public channels when possible. See SUPPORT.md.

Development setup

Prerequisites

• Bun
• Go 1.26+
• Docker with Compose

Install dependencies

bun install --frozen-lockfile

Use .env.example as the reference list of supported settings. Creating a local .env is optional for the default dev stack; only set variables when you want to override Docker or API defaults.

Start the full stack

docker compose -f docker-compose.yml -f docker-compose.build.yml up -d --build

This brings up Xdrop, Postgres, Redis, and MinIO at http://localhost:8080.

Run the frontend only

bun run dev:web

Run the API only

cd apps/api
go run ./cmd/api

What to run before opening a PR

Choose the checks that match your change:

Frontend changes

bun run lint:web
bun run typecheck:web
bun run test:web

Backend changes

cd apps/api
go test ./... -coverprofile=coverage.out -covermode=atomic

Full-stack or user-flow changes

bun run test:e2e

Formatting

bun run format:check

Coding conventions

• Follow .editorconfig, Prettier, and Go formatting defaults.
• Use PascalCase for React components, useX for hooks, camelCase for TypeScript utilities, and lowercase package names in Go.
• Keep tests close to the code they cover.
• Prefer focused pull requests over broad drive-by refactors.
• Add or update tests when behavior changes.

Pull request expectations

Please make it easy to review your change:

• Use a short imperative commit message, ideally in Conventional Commit style (feat:, fix:, docs:, test:).
• Explain the user-visible impact and any API, config, Docker, or data-model changes.
• List the verification steps you ran locally.
• Include screenshots or short recordings for UI changes.
• Update documentation when behavior, setup, or contributor workflows change.

If a change is large, split it into smaller reviewable steps whenever possible.

Review and maintainer expectations

• Maintainers make the final call on whether a change fits the project vision.
• We aim to acknowledge new issues and pull requests within 7 days, but this is a part-time project, so response times can vary.
• If you have not heard back after a week, a polite follow-up in the same thread is welcome.
• A closed issue or PR is not a judgment on the contributor. It usually means the change does not currently fit scope, timing, or maintenance capacity.

Good first contributions

If you are new to the project, good places to help include:

• improving docs and setup clarity
• adding or tightening frontend and API test coverage
• fixing accessibility issues
• polishing error states and recovery flows
• cleaning up rough edges in local development and CI

Thanks again for taking the time to contribute.