|
| 1 | +# Contributing to devbox |
| 2 | + |
| 3 | +Thanks for your interest in contributing to devbox! This guide covers everything you need to get started. |
| 4 | + |
| 5 | +## Development Setup |
| 6 | + |
| 7 | +**Requirements:** Go 1.24+ |
| 8 | + |
| 9 | +```bash |
| 10 | +git clone https://github.com/junixlabs/devbox.git |
| 11 | +cd devbox |
| 12 | +go build -o devbox ./cmd/devbox/ |
| 13 | +go test ./... |
| 14 | +``` |
| 15 | + |
| 16 | +## Project Structure |
| 17 | + |
| 18 | +``` |
| 19 | +cmd/devbox/ CLI entry point — all commands in main.go |
| 20 | +internal/ |
| 21 | + config/ devbox.yaml parsing and validation |
| 22 | + workspace/ Workspace model, Manager interface, resource limits |
| 23 | + ssh/ SSH remote command executor |
| 24 | + docker/ Docker Compose management via SSH |
| 25 | + tailscale/ Tailscale serve/unserve/status |
| 26 | + identity/ User identity resolution (Tailscale login) |
| 27 | + server/ Server pool management |
| 28 | + port/ Port auto-allocation registry |
| 29 | + metrics/ Resource metrics collector |
| 30 | + snapshot/ Snapshot & restore workspace state |
| 31 | + template/ Workspace templates (built-in + user-defined) |
| 32 | + tui/ Interactive TUI dashboard (Bubble Tea) |
| 33 | + plugin/ Plugin system (Provider/Hook interfaces) |
| 34 | + registry/ Community template registry |
| 35 | + ci/ CI/CD integration (GitHub Actions) |
| 36 | + errors/ Typed errors with suggestions |
| 37 | + ui/ CLI output helpers (spinners, colors) |
| 38 | + testutil/ Shared test helpers |
| 39 | + integration/ Multi-user E2E tests |
| 40 | +``` |
| 41 | + |
| 42 | +## Adding a New Command |
| 43 | + |
| 44 | +1. Create a function `yourCmd() *cobra.Command` in `cmd/devbox/main.go` |
| 45 | +2. Wire it: `rootCmd.AddCommand(yourCmd())` |
| 46 | +3. Follow existing patterns — use `RunE` (not `Run`), wrap errors with `fmt.Errorf("devbox your-cmd: %w", err)` |
| 47 | + |
| 48 | +## Adding a New Package |
| 49 | + |
| 50 | +1. Create `internal/yourpkg/yourpkg.go` |
| 51 | +2. Define an interface for the contract |
| 52 | +3. Implement the interface |
| 53 | +4. Import from CLI in `main.go` |
| 54 | + |
| 55 | +## Adding a Config Field |
| 56 | + |
| 57 | +1. Add to `DevboxConfig` struct in `internal/config/config.go` with a `yaml` tag |
| 58 | +2. Add validation in `Load()` if needed |
| 59 | +3. Update `devbox.yaml.example` |
| 60 | + |
| 61 | +## Writing Plugins |
| 62 | + |
| 63 | +See [docs/PLUGIN_API.md](docs/PLUGIN_API.md) for the full plugin development guide. |
| 64 | + |
| 65 | +Plugins implement `plugin.Provider` (custom workspace backends) or `plugin.Hook` (lifecycle callbacks). Create a directory with a `plugin.yaml` manifest and a Go binary, then install with `devbox plugin install <path>`. |
| 66 | + |
| 67 | +## Contributing Templates |
| 68 | + |
| 69 | +Templates are YAML files in `internal/template/builtin/`. To add a new built-in template: |
| 70 | + |
| 71 | +1. Create `internal/template/builtin/yourtemplate.yaml` |
| 72 | +2. Follow the schema from existing templates (name, image, services, ports) |
| 73 | +3. Register it in the built-in embed |
| 74 | + |
| 75 | +To share templates via the community registry, use `devbox template push`. |
| 76 | + |
| 77 | +## Code Style |
| 78 | + |
| 79 | +- **Error wrapping**: Always use `fmt.Errorf("context: %w", err)` |
| 80 | +- **Naming**: Go conventions — CamelCase exports, lowercase packages |
| 81 | +- **Interfaces**: Define contracts before implementations |
| 82 | +- **Tests**: Every package should have `_test.go` files |
| 83 | +- **No runtime dependencies**: Single binary, cross-compile friendly |
| 84 | + |
| 85 | +## Pull Request Process |
| 86 | + |
| 87 | +1. Fork and create a feature branch |
| 88 | +2. Make your changes with tests |
| 89 | +3. Run `go test ./...` and `go vet ./...` |
| 90 | +4. Submit a PR with a clear description of what and why |
| 91 | + |
| 92 | +## License |
| 93 | + |
| 94 | +By contributing, you agree that your contributions will be licensed under the project's license. |
0 commit comments