Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
108 lines (82 loc) · 4.87 KB

CONTRIBUTING.md

File metadata and controls

108 lines (82 loc) · 4.87 KB
Raw

Contributing to Dotty

Thanks for your interest in contributing! This project is a hackable starting point for self-hosting a voice stack on the M5Stack StackChan. Contributions that improve the wiring, fix bugs, add provider alternatives, or improve documentation are welcome.

How to propose changes

  1. Fork the repository on GitHub.
  2. Create a branch from main for your work.
  3. Make your changes (see guidelines below).
  4. Open a pull request against main with a clear description of what changed and why.

Small fixes (typos, broken links, clarifications) can go straight to a PR. For larger changes — new providers, architectural shifts, safety-related modifications — please open an issue first to discuss the approach.

Before submitting

  • Validate Docker Compose config:

    docker compose -f docker-compose.yml config --quiet

    This catches YAML syntax errors and invalid keys before they hit a live deployment.

  • Check for leaked placeholders or real values:

    • Files in this repo must use placeholders (<XIAOZHI_HOST>, <XIAOZHI_USER>, <ROBOT_NAME>, etc.) everywhere a real IP, hostname, username, or filesystem path would appear. See the "Configuring for your environment" table in README.md for the full list.
    • Never commit real IPs, hostnames, usernames, API keys, or filesystem paths. If your diff introduces a literal IP address or path that isn't a well-known default (like 127.0.0.1 or a standard port number), it probably needs to be a placeholder.

  • Test if possible. If you have a StackChan and a running deployment, verify the change works end-to-end. If you don't have the hardware, note that in the PR description — someone else can test it.

What lives where

Changes tend to fall into one of these areas:

Area Files Notes
Voice pipeline (xiaozhi-server) docker-compose.yml, .config.yaml, custom providers (pi_voice/, openai_compat/, edge_stream.py, fun_local.py, piper_local.py) These run inside the xiaozhi-server Docker container on the Docker host.
Brain / behaviour dotty-pi/, dotty-pi-ext/, dotty-behaviour/ Docker containers on the same host as xiaozhi-server. dotty-pi is the pi agent (voice brain); dotty-behaviour is the perception/greeter service.
Admin dashboard bridge.py, bridge/ FastAPI service on port 8081, running as a container on the Docker host.
Documentation README.md, SETUP.md, docs/, session-prompt.md Docs under docs/ follow conventions listed in docs/README.md (TL;DR at top, tables over prose, freshness footer).
CI .github/workflows/ Currently just the bridge Docker image build.

Code style

  • Python: Standard Python style. No specific formatter is enforced yet. Keep it readable, use type hints where they help, and match the style of the surrounding code.
  • YAML: Two-space indentation. Use comments to explain non-obvious values.
  • Markdown: Follow the conventions in docs/README.md — TL;DR at the top, tables for dense facts, relative links only.

Placeholder discipline

This is the most important contribution guideline. The repo is designed to be forked and configured per-deployment. Every value that varies between deployments must use a placeholder:

  • <XIAOZHI_HOST>, <XIAOZHI_USER>, <XIAOZHI_HOSTNAME>, <XIAOZHI_PATH>
  • <UNRAID_HOST>
  • <YOUR_NAME>, <ROBOT_NAME>

Port numbers (8000, 8003, 8080, 18789, 42617) are product-generic and do not need placeholders.

AI-assisted contributions

This project is openly AI-assisted, and your contributions can be too — using a coding agent on your PR is welcome and normal here. The one rule we hold ourselves (and you) to: acknowledge it. See AI_TRANSPARENCY.md for the full policy; the mechanics:

  • Keep the attribution your tool adds. If your agent writes a Co-Authored-By: trailer naming the model, leave it in — don't strip it to make the work look unaided.
  • Note agent help in the PR description when an AI drafted a substantial part of the change.
  • Review the output yourself before your name goes on it. The AI proposes; you decide and you're accountable. We don't merge work nobody understands.

Safety-related changes

The child-safety enforcement layer (persona prompt sandwich, audience framing in .config.yaml) is load-bearing. If your change touches the system prompt, turn suffix, or emoji enforcement logic, please describe your red-team testing in the PR description. See the commit history for examples of the red-team battery format.

Where to ask questions

Open a GitHub Issue. There is no chat channel or mailing list at this time.

License

By contributing, you agree that your contributions will be licensed under the same MIT License that covers the project.