Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
263 lines (183 loc) · 5.97 KB

CONTRIBUTING.md

File metadata and controls

263 lines (183 loc) · 5.97 KB
Raw

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

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

git clone https://github.com/arcoder181105/manufacturing-intelligence.git
cd manufacturing-intelligence

2. Set up Python environment

# 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

cd dashboard
npm install
cd ..

4. Install pre-commit hooks

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:

# 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:

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:

pre-commit run --all-files

To temporarily skip hooks (use sparingly):

git commit --no-verify -m "your message"

Running the Project

Option A — Docker (recommended, matches production)

# 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:

Option B — Run locally without Docker

Backend:

# Activate venv first
uvicorn api.main:app --reload --port 8000

Frontend:

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

# 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:

# 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.