Lukas
85d05ee582
- Add EditorConfig section to CONTRIBUTING.md with IDE plugins table - Remove Issue #28 from Tasks.md (pre-commit hooks now documented)
129 lines
3.3 KiB
Markdown
129 lines
3.3 KiB
Markdown
# Contributing to BanGUI
|
|
|
|
Welcome! This guide covers everything you need to know to set up your dev environment, understand the codebase, and submit changes.
|
|
|
|
---
|
|
|
|
## Dev Setup
|
|
|
|
### 1 — Clone and init
|
|
|
|
```bash
|
|
git clone <repo-url>
|
|
cd BanGUI
|
|
cp .env.example .env
|
|
python -c 'import secrets; print(secrets.token_hex(32))'
|
|
# paste output as BANGUI_SESSION_SECRET in .env
|
|
```
|
|
|
|
### 2 — Start the stack
|
|
|
|
```bash
|
|
make up
|
|
```
|
|
|
|
Backend: http://127.0.0.1:8000 · Frontend (Vite proxy): http://127.0.0.1:5173
|
|
|
|
### 3 — Editor Setup
|
|
|
|
Install **EditorConfig** plugin for your IDE. Ensures consistent formatting (indent style, line endings) across all editors.
|
|
|
|
| IDE | Plugin |
|
|
|-----|--------|
|
|
| VS Code | EditorConfig (ms-vscode.editorconfig) |
|
|
| PyCharm / IntelliJ | Built-in (enable in Settings → Editor → Code Style) |
|
|
| Vim / Neovim | editorconfig-vim |
|
|
| Sublime Text | EditorConfig |
|
|
|
|
### 4 — Pre-commit hooks
|
|
|
|
**Backend** (pre-commit, all languages):
|
|
|
|
```bash
|
|
pip install pre-commit
|
|
pre-commit install
|
|
```
|
|
|
|
**Frontend** (husky, TypeScript validation):
|
|
|
|
```bash
|
|
cd frontend && npm install
|
|
npx husky install
|
|
```
|
|
|
|
Hooks run automatically on every `git commit`. To run manually:
|
|
|
|
```bash
|
|
pre-commit run --all-files # backend hooks
|
|
cd frontend && npm run validate:types # frontend type check
|
|
```
|
|
|
|
---
|
|
|
|
## Project Structure
|
|
|
|
```
|
|
BanGUI/
|
|
├── backend/ Python FastAPI app
|
|
│ └── app/
|
|
│ ├── routers/ HTTP endpoint handlers
|
|
│ ├── services/ Business logic
|
|
│ ├── repos/ Data access
|
|
│ ├── models/ Pydantic request/response/domain models
|
|
│ └── utils/ Shared helpers
|
|
├── frontend/ React + TypeScript + Fluent UI v9
|
|
│ └── src/
|
|
│ ├── pages/ Route-level page components
|
|
│ ├── components/ Reusable UI components
|
|
│ ├── hooks/ Custom React hooks
|
|
│ └── types/ Shared TypeScript types
|
|
├── Docs/ Architecture, design, and feature documentation
|
|
└── Docker/ Container compose files
|
|
```
|
|
|
|
---
|
|
|
|
## Code Quality
|
|
|
|
| Tool | Scope | Command |
|
|
|---|---|---|
|
|
| `ruff` | Backend linting | `cd backend && ruff check .` |
|
|
| `ruff-format` | Backend formatting | `cd backend && ruff format .` |
|
|
| `mypy --strict` | Backend type checking | `cd backend && mypy --strict app` |
|
|
| `tsc --noEmit` | Frontend type checking | `cd frontend && tsc --noEmit` |
|
|
| `eslint` | Frontend linting | `cd frontend && eslint src` |
|
|
| `prettier --check` | Frontend formatting | `cd frontend && prettier --check src` |
|
|
|
|
**All checks must pass before committing.** CI runs the same suite.
|
|
|
|
---
|
|
|
|
## Testing
|
|
|
|
```bash
|
|
# Backend
|
|
cd backend && pytest --cov=app --cov-report=term-missing
|
|
|
|
# Frontend — run once
|
|
cd frontend && npm test
|
|
```
|
|
|
|
---
|
|
|
|
## Stack
|
|
|
|
| Layer | Stack |
|
|
|---|---|
|
|
| Backend | Python 3.12+, FastAPI, Pydantic v2, aiosqlite, structlog |
|
|
| Frontend | TypeScript, React, Fluent UI v9, Vite |
|
|
| Container | Docker Compose (development + production) |
|
|
|
|
---
|
|
|
|
## Key Docs
|
|
|
|
- [Instructions.md](Docs/Instructions.md) — Agent operating rules
|
|
- [Backend-Development.md](Docs/Backend-Development.md) — Backend conventions
|
|
- [Web-Development.md](Docs/Web-Development.md) — Frontend conventions
|
|
- [Features.md](Docs/Features.md) — Complete feature list
|
|
- [Architekture.md](Docs/Architekture.md) — System architecture |