docs: add CONTRIBUTING guide, dev requirements, and pre-commit hooks

Author: ARCoder181105

.pre-commit-config.yaml

@@ -0,0 +1,17 @@
+repos:
+  - repo: https://github.com/pycqa/isort
+    rev: 5.13.2
+    hooks:
+      - id: isort
+        args: ["--profile", "black"]
+
+  - repo: https://github.com/psf/black
+    rev: 24.3.0
+    hooks:
+      - id: black
+
+  - repo: https://github.com/pycqa/flake8
+    rev: 7.0.0
+    hooks:
+      - id: flake8
+        args: ["--select=E9,F63,F7,F82"]

CONTRIBUTING.md

@@ -0,0 +1,263 @@
+# Contributing to PRISM
+
+**Predictive Reliability & Intelligence for Smart Manufacturing**
+
+This guide covers everything you need to set up your local development environment, follow the project's code standards, and contribute effectively.
+
+---
+
+## Table of Contents
+
+- [Prerequisites](#prerequisites)
+- [Local Setup](#local-setup)
+- [Development Tools](#development-tools)
+- [Pre-commit Hooks](#pre-commit-hooks)
+- [Running the Project](#running-the-project)
+- [Code Standards](#code-standards)
+- [Testing](#testing)
+- [Commit Message Convention](#commit-message-convention)
+- [Releasing](#releasing)
+
+---
+
+## Prerequisites
+
+Make sure you have the following installed before starting:
+
+| Tool | Version | Purpose |
+|------|---------|---------|
+| Python | 3.10 or 3.11 | Backend runtime |
+| Node.js | 20+ | Frontend runtime |
+| Docker Desktop | Latest | Container builds |
+| Git | Any | Version control |
+
+---
+
+## Local Setup
+
+### 1. Clone the repo
+
+```bash
+git clone https://github.com/arcoder181105/manufacturing-intelligence.git
+cd manufacturing-intelligence
+```
+
+### 2. Set up Python environment
+
+```bash
+# Create a virtual environment
+python -m venv venv
+
+# Activate it
+# Windows:
+venv\Scripts\activate
+# Mac/Linux:
+source venv/bin/activate
+
+# Install app dependencies
+pip install -r requirements.txt
+
+# Install dev dependencies (linting, testing, pre-commit)
+pip install -r requirements-dev.txt
+```
+
+### 3. Set up frontend
+
+```bash
+cd dashboard
+npm install
+cd ..
+```
+
+### 4. Install pre-commit hooks
+
+```bash
+pre-commit install
+```
+
+This installs git hooks that automatically run formatters before every commit — so CI never fails due to formatting issues.
+
+---
+
+## Development Tools
+
+All dev tools are listed in `requirements-dev.txt`. Here's what each one does:
+
+| Tool | Command | Purpose |
+|------|---------|---------|
+| `black` | `black src/ api/ tests/` | Auto-formats Python code |
+| `isort` | `isort src/ api/ tests/` | Sorts Python imports |
+| `flake8` | `flake8 src/ api/ tests/` | Lints for syntax errors |
+| `pytest` | `pytest tests/` | Runs the test suite |
+| `pre-commit` | runs automatically | Runs formatters before each commit |
+
+### Manually running formatters
+
+If you want to run them manually without committing:
+
+```bash
+# Fix import order
+isort src/ api/ tests/
+
+# Fix code formatting
+black src/ api/ tests/
+
+# Check for lint errors (does not auto-fix)
+flake8 src/ api/ tests/ --select=E9,F63,F7,F82
+```
+
+---
+
+## Pre-commit Hooks
+
+Once installed via `pre-commit install`, the hooks run automatically on every `git commit`. You never need to think about formatting again.
+
+If a hook fixes a file, the commit will be blocked and you'll see which files were changed. Just `git add` the fixed files and commit again:
+
+```bash
+git commit -m "your message"
+# hook runs, fixes imports → commit blocked
+git add src/
+git commit -m "your message"
+# passes ✅
+```
+
+To manually run hooks on all files without committing:
+
+```bash
+pre-commit run --all-files
+```
+
+To temporarily skip hooks (use sparingly):
+
+```bash
+git commit --no-verify -m "your message"
+```
+
+---
+
+## Running the Project
+
+### Option A — Docker (recommended, matches production)
+
+```bash
+# Build and start both services
+docker-compose up -d --build
+
+# View logs
+docker-compose logs -f
+
+# Stop
+docker-compose down
+```
+
+Services will be available at:
+- Frontend: http://localhost:3000
+- Backend API: http://localhost:8000
+- API Docs: http://localhost:8000/docs
+
+### Option B — Run locally without Docker
+
+**Backend:**
+```bash
+# Activate venv first
+uvicorn api.main:app --reload --port 8000
+```
+
+**Frontend:**
+```bash
+cd dashboard
+npm run dev
+```
+
+---
+
+## Code Standards
+
+### Python
+
+- **Formatter:** `black` (line length 88)
+- **Import sorter:** `isort` (compatible with black)
+- **Linter:** `flake8` (syntax errors only — formatting is handled by black)
+- **Style:** Follow existing patterns in `src/` and `api/`
+
+### TypeScript / React
+
+- **Formatter:** Prettier (via `npm run lint`)
+- **Framework:** Next.js 16 App Router
+- Keep components in `dashboard/src/components/`
+- Keep API calls in `dashboard/src/lib/`
+
+### General
+
+- Never commit `.env` files — use `.env.example` as a template
+- Never commit model files or large data files — these are mounted as Docker volumes
+- Keep `requirements.txt` for runtime dependencies only
+- Keep `requirements-dev.txt` for developer tools only
+
+---
+
+## Testing
+
+```bash
+# Run all tests
+pytest tests/ -v
+
+# Run with coverage report
+pytest tests/ --cov=src --cov=api --cov-report=term-missing
+
+# Run a specific test file
+pytest tests/test_api.py -v
+
+# Run a specific test
+pytest tests/test_api.py::test_health_endpoint -v
+```
+
+Tests must pass on both Python 3.10 and 3.11 — the CI pipeline tests both automatically.
+
+---
+
+## Commit Message Convention
+
+We use a simple prefix convention so the release changelog is generated automatically:
+
+| Prefix | When to use | Example |
+|--------|-------------|---------|
+| `feat:` | New feature | `feat: add batch comparison endpoint` |
+| `fix:` | Bug fix | `fix: handle missing model gracefully` |
+| `perf:` | Performance improvement | `perf: cache SHAP values on startup` |
+| `ci:` | CI/CD changes | `ci: add Python 3.11 to test matrix` |
+| `docker:` | Docker changes | `docker: reduce backend image size` |
+| `docs:` | Documentation | `docs: update API endpoint reference` |
+| `test:` | Test changes | `test: add integration tests for predict endpoint` |
+| `refactor:` | Code cleanup | `refactor: extract prediction logic to service layer` |
+
+---
+
+## Releasing
+
+Releases are fully automated — just tag and push:
+
+```bash
+# Stable release
+git tag v1.0.0
+git push origin v1.0.0
+
+# Pre-release
+git tag v1.0.0-beta.1
+git push origin v1.0.0-beta.1
+```
+
+This triggers the release workflow which:
+- Validates the version format
+- Auto-generates a changelog from commits
+- Creates a GitHub Release with release notes
+- Builds and pushes versioned Docker images to GHCR
+
+See `RELEASES.md` for full details on the release process.
+
+---
+
+## Questions?
+
+Open an issue on GitHub or check the existing issues before starting work on a new feature.