150 lines
4.4 KiB
Markdown
150 lines
4.4 KiB
Markdown
# 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.
|