CONTRIBUTING.md

Contributing to Repo Doctor

Thank you for your interest in contributing to Repo Doctor! This document outlines the process for contributing to this project.

---

Development Setup

Prerequisites

• Node.js ≥ 20.11
• Docker & Docker Compose (for PostgreSQL and Redis)
• npm (ships with Node.js)

Local Environment

# Clone the repository
git clone https://github.com/your-org/repo-doctor.git
cd repo-doctor

# Start databases
docker compose up -d

# Install dependencies
npm install

# Generate Prisma client
npm run db:generate

# Run migrations
npm run db:migrate

# Start dev servers (API + Web concurrently)
npm run dev

The frontend runs at http://localhost:5173 and the API at http://localhost:4000.

---

Branch Naming

Use descriptive branch names with a category prefix:

Prefix	Purpose
fix/	Bug fixes
docs/	Documentation changes
refactor/	Code cleanup without behavior change
chore/	Tooling, CI, dependency updates
test/	Adding or improving tests

Example: fix/redis-cache-fallback-timeout

---

Pull Request Checklist

Before submitting a PR, verify:

• All tests pass: npm test
• TypeScript compiles: npm run build
• No new lint warnings
• Changes are documented if user-facing
• Commit messages are clear and descriptive
• Screenshots included for any UI changes

---

Code Standards

• TypeScript: Strict mode enabled. No any types unless wrapped with explicit casts and documented.
• Styling: Vanilla CSS in styles.css. Dark-mode-first. No Tailwind.
• Components: React functional components with hooks. No class components.
• Testing: Vitest for unit and integration tests. Tests live alongside source files (*.test.ts).
• Architecture rule: Deterministic analysis is the source of truth. AI is used only for explanation, never for scoring or risk calculation.

---

Reporting Issues

• Bugs: Use the Bug Report template.
• Features: Use the Feature Request template.

---

Code of Conduct

Be respectful, constructive, and inclusive. We follow the Contributor Covenant code of conduct.