From c9cd6a08fcaa1baca86a443f0a19d279fa742ca4 Mon Sep 17 00:00:00 2001 From: Pouzor Date: Tue, 21 Apr 2026 12:23:50 +0200 Subject: [PATCH] add CONTRIBUTING.md --- CONTRIBUTING.md | 276 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 276 insertions(+) create mode 100644 CONTRIBUTING.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..0b0fa90 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,276 @@ +# Contributing to Homelable + +Thanks for taking the time to contribute! This document covers everything you need to get started. + +--- + +## Table of Contents + +- [Ways to Contribute](#ways-to-contribute) +- [Reporting Bugs](#reporting-bugs) +- [Suggesting Features](#suggesting-features) +- [Development Setup](#development-setup) +- [Project Structure](#project-structure) +- [Coding Standards](#coding-standards) +- [Testing](#testing) +- [Submitting a Pull Request](#submitting-a-pull-request) +- [Commit Message Format](#commit-message-format) + +--- + +## Ways to Contribute + +- Report bugs or unexpected behavior +- Suggest new features or improvements +- Fix open issues (check the [issue tracker](https://github.com/Pouzor/homelable/issues)) +- Improve documentation +- Add service signatures to `service_signatures.json` + +--- + +## Reporting Bugs + +Before opening an issue, search existing ones to avoid duplicates. + +When filing a bug, include: + +- **Homelable version** (visible in the sidebar bottom-left) +- **Deployment method** (Docker Compose, Proxmox LXC, source) +- **Steps to reproduce** +- **Expected vs actual behavior** +- **Relevant logs** (`docker compose logs backend` / `docker compose logs frontend`) +- **Browser console errors** if it's a UI issue + +--- + +## Suggesting Features + +Open an issue with the `enhancement` label. Describe: + +- The problem you're trying to solve +- Your proposed solution +- Any alternatives you considered + +For large changes, discuss first before writing code — it avoids wasted effort. + +--- + +## Development Setup + +### Prerequisites + +- **Node.js 20+** and **npm** +- **Python 3.11–3.13** (3.14 not yet supported by all dependencies) +- **nmap** installed on your system (required for scanner) +- **Docker + Docker Compose** (optional, for full-stack testing) + +### 1. Clone the repo + +```bash +git clone https://github.com/Pouzor/homelable.git +cd homelable +``` + +### 2. Backend + +```bash +cd backend +python3.13 -m venv .venv +source .venv/bin/activate # Windows: .venv\Scripts\activate +pip install -r requirements.txt + +# Copy and configure environment +cp .env.example .env # edit AUTH_PASSWORD_HASH, SECRET_KEY, etc. + +# Start the backend (auto-reloads on change) +uvicorn app.main:app --reload --port 8000 +``` + +API docs available at `http://localhost:8000/docs`. + +### 3. Frontend + +```bash +cd frontend +npm install +npm run dev # http://localhost:5173 +``` + +Vite proxies `/api` to `localhost:8000` — the backend must be running. + +### 4. Verify tooling + +```bash +./scripts/verify-tooling.sh +``` + +--- + +## Project Structure + +``` +homelable/ +├── frontend/src/ +│ ├── components/ +│ │ ├── canvas/ # React Flow canvas, custom nodes & edges +│ │ ├── panels/ # Sidebar, detail panel, toolbar +│ │ ├── modals/ # Add/edit node, scan config, pending devices +│ │ └── ui/ # Shadcn/ui base components +│ ├── stores/ # Zustand state (canvas, auth, scan) +│ ├── hooks/ # Custom React hooks +│ ├── types/ # TypeScript interfaces & enums +│ ├── api/ # Axios client & typed endpoints +│ └── utils/ # Layout, export, color helpers +│ +├── backend/app/ +│ ├── api/routes/ # FastAPI route handlers +│ ├── services/ # Scanner, status checker, canvas service +│ ├── db/ # SQLAlchemy models, Alembic migrations +│ ├── schemas/ # Pydantic request/response schemas +│ └── core/ # Config, JWT, scheduler +│ +├── docker/ # Nginx configs +├── scripts/ # LXC bootstrap, dev helpers +└── mcp/ # MCP server (AI integration) +``` + +--- + +## Coding Standards + +### General + +- No untested code merged — every feature or fix must include tests +- Keep changes focused — one concern per PR + +### Frontend (TypeScript + React) + +- Strict TypeScript — no `any`, no type assertions unless truly necessary +- React Flow node domain fields go in `node.data`, never on the node root +- State management via Zustand stores — no prop drilling beyond 2 levels +- Styling via TailwindCSS utility classes — follow the existing [design system](#design-system) +- Run before committing: + ```bash + cd frontend + npm run lint + npm run typecheck + npm test + ``` + +### Backend (Python + FastAPI) + +- Python 3.11+ syntax +- Pydantic v2 schemas for all request/response types +- SQLAlchemy async sessions — never block the event loop +- Scanner logic runs in a background thread — never in an async route directly +- All schema changes via Alembic migrations — never modify tables directly +- Run before committing: + ```bash + cd backend + source .venv/bin/activate + ruff check . + pytest + ``` + +### Design System + +| Token | Value | +|---|---| +| Background | `#0d1117` | +| Surface | `#161b22` | +| Card | `#21262d` | +| Accent cyan | `#00d4ff` | +| Online | `#39d353` | +| Offline | `#f85149` | +| Pending | `#e3b341` | +| Font (UI) | Inter | +| Font (IPs/ports) | JetBrains Mono | + +--- + +## Testing + +Tests run automatically via a pre-commit hook when frontend or backend files are staged. + +### Frontend + +```bash +cd frontend +npm test # run all tests +npm run test:coverage # with coverage report +``` + +Test files live in `__tests__/` next to their module, named `*.test.ts(x)`. + +**What to test:** Zustand store actions, utility functions, non-trivial component logic. + +### Backend + +```bash +cd backend +source .venv/bin/activate +pytest # run all tests +pytest -v tests/test_nodes.py # single file +``` + +Test files live in `backend/tests/test_*.py`. + +**What to test:** all API routes (happy path + error cases), auth flows, service logic. + +Use the `client` and `headers` fixtures from `conftest.py` — they provide an in-memory SQLite database so tests are isolated and fast. + +--- + +## Submitting a Pull Request + +1. **Fork** the repo and create a branch from `main`: + ```bash + git checkout -b feat/my-feature + ``` + +2. **Make your changes** — include tests. + +3. **Run the full test suite** (frontend + backend) and make sure everything passes. + +4. **Open a PR** against `main`: + - Use a clear title (see commit format below) + - Describe what changed and why + - Reference any related issues (`Closes #123`) + - Include screenshots for UI changes + +5. Keep the PR focused — one feature or fix per PR. Large refactors should be discussed in an issue first. + +--- + +## Commit Message Format + +Follow [Conventional Commits](https://www.conventionalcommits.org/): + +``` +: + +[optional body] +``` + +| Type | When to use | +|---|---| +| `feat` | New feature | +| `fix` | Bug fix | +| `docs` | Documentation only | +| `refactor` | Code change with no behavior change | +| `test` | Adding or fixing tests | +| `chore` | Build, deps, tooling | + +**Examples:** +``` +feat: add logout button to sidebar +fix: stop click propagation on pending device checkbox +docs: add CONTRIBUTING.md +``` + + +--- + +## Questions? + +Open a [GitHub Discussion](https://github.com/Pouzor/homelable/discussions) or drop a comment on a relevant issue.