# 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`](README.md) for the current project status and local setup.
- Follow [`MESSAGING.md`](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`](SECURITY.md) instead of
  filing a public issue.
- Keep general questions and troubleshooting in public channels when possible. See
  [`SUPPORT.md`](SUPPORT.md).

## Development setup

### Prerequisites

- Bun
- Go 1.26+
- Docker with Compose

### Install dependencies

```bash
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

```bash
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

```bash
bun run dev:web
```

### Run the API only

```bash
cd apps/api
go run ./cmd/api
```

## What to run before opening a PR

Choose the checks that match your change:

### Frontend changes

```bash
bun run lint:web
bun run typecheck:web
bun run test:web
```

### Backend changes

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

### Full-stack or user-flow changes

```bash
bun run test:e2e
```

### Formatting

```bash
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.