Skip to content

GETTING_STARTED.md

Latest commit

 

History

History
250 lines (175 loc) · 6.46 KB

GETTING_STARTED.md

File metadata and controls

250 lines (175 loc) · 6.46 KB
Raw

Getting Started

The supported development path is WSL2 + VS Code Remote WSL on Windows, or native on macOS/Linux. A Dev Container option is also available — see Dev Container (optional) below.

TL;DR

git clone https://github.com/solentlabs/cable_modem_monitor.git
cd cable_modem_monitor
git lfs install      # required for HAR test fixtures
./scripts/setup.sh   # creates .venv and installs all dependencies
code .

When VS Code opens, run:

make validate

If anything in the setup fails: ./scripts/verify-setup.sh.

Prerequisites

Tool All platforms Windows-specific
Git required required
Git LFS required (HAR fixtures) required
Python 3.12 required required (install inside WSL2)
VS Code required required (installed on Windows side)
Docker Desktop required for HA testing WSL2 backend enabled
WSL2 + Ubuntu — required (wsl --install from PowerShell as admin)

Windows users: clone the repo inside WSL2 (e.g. ~/projects/), not on the Windows filesystem (/mnt/c/). The 9P bridge is dramatically slower and breaks file watchers.

After opening in VS Code

Notification What to do
"Install recommended extensions?" Click Install — all required.
"GitLens" / "CodeQL" extras Optional; dismiss if not needed.

Validation

make validate       # Ruff + Black + quick tests (~30s)
make validate-ci    # Full ruff + pytest (2–5 min) — run before push
make test           # All three test suites (Core, Catalog, HA)

Or use the Testing panel (beaker icon) — pytest tests auto-discover. If they don't appear: refresh the panel, or check the Python interpreter in the bottom-left status bar.

CodeQL tests live in cable-modem-monitor-ql/tests/ and don't appear in the Testing panel. Run them via GitHub Actions or codeql test run.

Home Assistant container management

VS Code tasks (Ctrl+Shift+P → Tasks: Run Task):

Task Purpose
🚀 HA: Start Start HA with info logging (restarts if already running)
🚀 HA: Start (Debug) Start HA with debug logging for all integration namespaces
⏹️ HA: Stop Stop the HA container
📋 HA: View Logs Tail HA logs in real time
🗑️ HA: Clean All Data (Reset) Wipe HA's local test config (users, integrations, settings)

After starting, open http://localhost:8123.

Daily workflow

git checkout -b feature/my-change
# edit, run tests via Testing panel or `make test-quick`
make validate
git commit -am "..."
git push -u origin feature/my-change

Pre-commit hooks auto-format with Black and lint with Ruff. See CONTRIBUTING.md for PR guidelines and commit message conventions.

Git worktrees

Worktrees share the main repo's .venv automatically. Every dev script (run-python.sh, run-pyright.sh, activate_venv.sh, pre-commit hooks) calls scripts/dev/resolve-venv.sh, which:

  1. Looks for .venv in the current directory.
  2. Falls back to the main worktree via git rev-parse --git-common-dir.

Create one anywhere convenient (a sibling directory, or your team's preferred worktree location):

git worktree add ../my-feature feature/v3.14.0
cd ../my-feature

A .venv symlink is created on first use (gitignored). VS Code, Pylance, and the test runner all work without setup.

Windows / WSL2 setup

If you're on Windows and don't yet have WSL2:

# PowerShell as Administrator
wsl --install
# Restart when prompted; Ubuntu launches automatically afterward.

In Ubuntu:

cat /etc/os-release      # confirm Ubuntu 22.04 or 24.04

# Install Docker (or use Docker Desktop with WSL2 backend)
sudo apt install docker.io
sudo usermod -aG docker $USER
exit                     # log back in to apply group

# Verify
docker run hello-world

Then clone the repo under ~/projects/ and run code . — VS Code detects WSL2, installs Remote-WSL, and opens the folder. The bottom-left status bar should read "WSL: Ubuntu".

WSL2 memory tuning

If WSL2 uses too much RAM, create C:\Users\<username>\.wslconfig:

[wsl2]
memory=8GB
processors=4

Then wsl --shutdown.

Dev Container (optional)

A Dev Container configuration is available for contributors who prefer a fully isolated environment. It requires Docker and the Dev Containers extension.

# After cloning, open VS Code and click "Reopen in Container"
# First build takes 2–5 minutes; subsequent opens are instant.

The container installs all dependencies automatically via .devcontainer/post-create.sh. If tools like ruff or black are missing after a container rebuild, run the Fix Dev Container VS Code task.

Troubleshooting

Container won't start

docker ps                # is Docker running?

If not, start Docker Desktop. Then in VS Code: F1 → Dev Containers: Rebuild Container.

Port 8123 already in use

docker ps
docker stop ha-cable-modem-test

Or run the ⏹️ HA: Stop task.

HAR files appear empty / JSONDecodeError

HAR fixtures are stored in Git LFS. If a file is ~130 bytes starting with version https://git-lfs., LFS hasn't fetched the content:

git lfs install   # once per machine
git lfs pull

Pre-commit hooks failing

make format                          # auto-fix
make lint                            # see what's wrong
pre-commit install --install-hooks   # update hooks

Permission denied on scripts (Linux/WSL2)

chmod +x scripts/*.sh scripts/dev/*.sh

Docker permission denied

groups                               # should include 'docker'
sudo usermod -aG docker $USER
exit                                 # log back in

Tests not appearing in Testing panel

  1. Check Python interpreter in bottom-left status bar (should be /usr/local/bin/python3.12 inside the container).
  2. Refresh: Testing panel → refresh icon, or F1 → Python: Refresh Tests.

Getting help