Home

Community

Contributing

KillTheHost is built in the open. Bug reports, discussion, and pull requests are all welcome — here is how to make them count.

Philosophy

  • Stay small. Every added feature is a support burden — prefer composition over expansion.
  • Stay predictable. Defaults should match what most users already run.
  • Stay portable. A contribution that only works on one distro is half-finished.

Filing issues

Before you open an issue, make sure it isn't already tracked. A good report includes:

  • KillTheHost version (killthehost --version).
  • Host OS and Docker version.
  • Steps to reproduce, expected result, actual result.
  • A diagnostics bundle generated with killthehost doctor --bundle.

Running locally

bash
$git clone https://github.com/Official-phdesigns/KillTheHost.git
$cd KillTheHost
$python3 -m venv .venv
$source .venv/bin/activate
$pip install -e '.[dev]'
# Launch the panel in watch mode
$killthehost dev

Panel front-end

The control panel uses server-rendered templates with a small amount of Alpine.js. CSS lives in panel/static/css/ and is compiled with tailwindcss.

bash
$cd panel
$npm install
$npm run watch

Code style

  • Python is formatted with black and linted with ruff.
  • Type hints are required on public functions.
  • Shell scripts are POSIX-sh where possible and use shellcheck in CI.
  • Commit messages follow Conventional Commits.

Tests

The test suite is split into unit, integration, and end-to-end packs.

bash
# Unit only
$pytest -m "not integration and not e2e"
# Integration (requires Docker)
$pytest -m integration
# Full e2e
$pytest -m e2e

New features should ship with tests. Bug fixes should add a regression test that fails on main.

Submitting pull requests

  1. Fork the repository and create a topic branch — feat/phpmngr-xdebug, fix/tunnel-reconnect, etc.
  2. Keep commits focused — rebase if you go down a dead end.
  3. Open the PR against main. Tick every checkbox in the PR template.
  4. CI runs lint, tests, and a dry-run build. All checks must pass before review.
  5. At least one maintainer approval is required to merge.

Security disclosure

Please do not open public issues for security vulnerabilities. Email [email protected] with a description and any proof of concept. We acknowledge within 48 hours and publish a coordinated advisory once a fix is available.

Previous

FAQ