2026-07-15 11:56:14 -07:00
|
|
|
# Contributing to BearDrive
|
|
|
|
|
|
|
|
|
|
Thanks for wanting to help. BearDrive is early (pre-1.0) and moving fast —
|
|
|
|
|
small, focused PRs land quickest, and an issue or discussion before a big
|
|
|
|
|
change saves everyone time.
|
|
|
|
|
|
|
|
|
|
## Build & test
|
|
|
|
|
|
|
|
|
|
```sh
|
|
|
|
|
go build ./... # everything, no CGO, no Node needed
|
|
|
|
|
go vet ./...
|
|
|
|
|
go test ./... # full suite
|
|
|
|
|
go test ./internal/syncer -run TestConflict -v # one test
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
Set `BDRIVE_HOME=/some/tmp/dir` when testing the CLI by hand so you never
|
|
|
|
|
touch your real `~/.bdrive`.
|
|
|
|
|
|
|
|
|
|
## Run a local hub
|
|
|
|
|
|
|
|
|
|
```sh
|
|
|
|
|
go build -o bdrive ./cmd/bdrive
|
|
|
|
|
mkdir -p /tmp/hub-storage
|
2026-07-30 17:46:58 +09:00
|
|
|
./bdrive serve /tmp/hub-storage --addr :8080 --upload # plain-folder viewer
|
2026-07-15 11:56:14 -07:00
|
|
|
```
|
|
|
|
|
|
|
|
|
|
For hub mode with accounts, see the self-hosting guide
|
|
|
|
|
([docs/self-hosting.md](docs/self-hosting.md)). The e2e test harness
|
|
|
|
|
(`BDRIVE_E2E_SERVE=1 go test -run TestE2EServe ./internal/webapp`) starts a
|
|
|
|
|
seeded hub on :8993 with test accounts — handy for frontend work.
|
|
|
|
|
|
|
|
|
|
## The rules that matter here
|
|
|
|
|
|
|
|
|
|
- **Sync changes need multi-device tests.** The real coverage lives in
|
|
|
|
|
`internal/syncer/syncer_test.go`: simulated devices syncing through a
|
|
|
|
|
shared remote, driven cycle by cycle. A new sync behavior without a
|
|
|
|
|
multi-device test is untested where it matters.
|
|
|
|
|
- **Never break sync.** Errors degrade to offline and retry next cycle;
|
|
|
|
|
a cycle must not fail because a side feature (telemetry, hooks) did.
|
|
|
|
|
Read the invariants section in [CLAUDE.md](CLAUDE.md) before touching
|
|
|
|
|
`internal/syncer`, `internal/journal`, or `internal/store` — replay
|
|
|
|
|
determinism and journal ownership are the whole concurrency story.
|
|
|
|
|
- **Frontend changes rebuild the committed assets.** The web UI lives in
|
|
|
|
|
`internal/webapp/frontend` (React + TS, Vite); its build output is
|
|
|
|
|
committed at `internal/webapp/static` so `go build` needs no Node.
|
|
|
|
|
After changing `frontend/src`: `npm run build`, commit the new
|
|
|
|
|
`static/`, and keep `npm run e2e` green. `frontend/check-dist.sh`
|
|
|
|
|
verifies freshness.
|
|
|
|
|
- **Docs travel with behavior.** Changing CLI commands, flags, or output
|
|
|
|
|
means updating both `README.md` and `plugin/skills/beardrive/SKILL.md`
|
|
|
|
|
— the skill is what makes agents beardrive-aware and must match the
|
|
|
|
|
binary.
|
|
|
|
|
|
|
|
|
|
## Where to start
|
|
|
|
|
|
|
|
|
|
[ROADMAP.md](ROADMAP.md) marks items we'd love help with, and issues
|
|
|
|
|
labeled `good first issue` / `help wanted` are curated to be approachable.
|
|
|
|
|
Bug reports with a reproduction (the issue form asks for `bdrive version`,
|
|
|
|
|
OS, and hub vs plain-folder mode) are gold.
|
|
|
|
|
|
|
|
|
|
## Conduct
|
|
|
|
|
|
|
|
|
|
Be kind, be direct, assume good intent. Maintainers reserve the right to
|
|
|
|
|
moderate. Security issues: email snow@runbear.io rather than opening a
|
|
|
|
|
public issue.
|
