GitHub
Contribute

Help build Drover.

This page is a summary. CONTRIBUTING.md is the reference.

Good first issuesHelp wanted

Where to start

  • good first issue: small tasks for new contributors.
  • documentation: changes to the docs and this site.
  • help wanted: tasks where the maintainers want help.

For a feature, open an issue before you write the code.

Set up a development environment

You need Python 3.11 or later, uv, a PostgreSQL database and one agent CLI.

  1. Clone the repository and initialize the hub.
git clone https://github.com/arniesaha/drover.git
cd drover
uv sync --extra dev
git config core.hooksPath .githooks

export DROVER_CONTROL_DSN='postgresql://USER:PASSWORD@HOST/DATABASE'
uv run drover-server init
uv run drover-server control-store init

The core.hooksPath line enables a pre-commit hook. The hook rejects a commit that contains a private path, a private address or a credential.

  1. Start the hub and a host.
# terminal 1: the hub
uv run drover-server run

# terminal 2: a local host
uv run drover-harnessd \
  --host-id local-dev \
  --display-name "Local Dev Host" \
  --kind macos \
  --listen 127.0.0.1:7081 \
  --local-url http://127.0.0.1:7081 \
  --central-url http://127.0.0.1:7080

iOS app

You need Xcode 16 or later.

brew install xcodegen
cd apps/drover
xcodegen generate
open Drover.xcodeproj

Select your Apple development team and run the Drover scheme. See the iOS guide.

This site

The site is in site/ in the same repository.

cd site
npm ci
npm run dev    # local preview
npm test       # build, then run the checks

Run the tests

uv run pytest -n auto                              # all Python tests
uv run pytest tests/test_check_public_release.py   # one module
uv run black --check .
uv run isort --check-only .
make docs                                          # Markdown links
  • Format Python with Black at line length 88. Sort imports with isort.
  • Tests that need PostgreSQL skip when it is not available. Continuous integration (CI) runs them.

Open a pull request

  1. Make sure the tests pass.
  2. Update the docs for each change a user can see.
  3. Add an entry below [Unreleased] in CHANGELOG.md.
  4. Describe the change and how you validated it.
  5. Identify breaking changes.

Use Conventional Commits, for example fix(harnessd): handle PTY session termination gracefully. One reviewer must approve.

Code of conduct

Be respectful and professional. See the code of conduct.

Security reports

Do not report a vulnerability in a public issue. Follow SECURITY.md. Do not put credentials, private addresses or session content in an issue.