Contributing

Contributing

Thank you for your interest in contributing to MomShell! This guide covers the collaboration standards and development workflow for contributors.

Getting Started

For environment setup and running the project, see:

• Getting Started - Prerequisites, installation, and running
• Development Guide - Development environment setup

IDE Configuration

We recommend VS Code for development. Configure it as follows:

1. Select Python Interpreter:

   • Open Command Palette (Ctrl+Shift+P / Cmd+Shift+P)
   • Type and select Python: Select Interpreter
   • Choose the option containing backend/.venv

2. Install Recommended Extensions:

   • Python (Microsoft)
   • Ruff (Astral Software) - Code formatting and linting
   • Mypy (Microsoft) - Static type checking

Development Workflow

Daily Sync

Before writing code, update your local branch and sync dependencies:

git checkout dev
git pull --rebase origin dev

cd backend && uv sync && cd ..
cd frontend && npm install && cd ..

Code Quality Checks

Before committing, run these checks locally:

# Using Make (recommended)
make lint       # Run all linters
make format     # Format all code
make typecheck  # Run type checkers
make check      # Run lint + typecheck

Or manually:

# Backend
cd backend
uv run ruff format .
uv run ruff check . --fix
uv run mypy app/

# Frontend
cd frontend
npm run lint
npm run build

Dependency Management

Backend (Python) - Do not use pip directly:

cd backend
uv add numpy          # Production dependency
uv add --dev ruff     # Development dependency

Frontend (Node.js):

cd frontend
npm install axios         # Production dependency
npm install -D @types/node  # Development dependency

Collaboration Standards

Lock File Management

Backend (backend/ directory):

• uv.lock - Auto-generated. Do not edit manually. Must be committed.
• requirements.txt - Auto-generated by uv export. Do not edit manually.
• Conflict Resolution: Run cd backend && uv lock && uv export > requirements.txt

Frontend:

• package-lock.json - Auto-generated. Do not edit manually. Must be committed.
• Conflict Resolution: Delete package-lock.json, run npm install

Large File Handling

• Verify large binary files (.pt, .parquet, .db) are listed in .gitattributes for LFS
• Never commit files larger than 10MB without LFS

Sensitive Files

Never commit:

• .env - Use .env.example as template
• Credential files (credentials.json, *.pem, *.key)
• __pycache__/, node_modules/, .next/, out/

Code Standards

Backend (Python) - Enforced by Ruff and Mypy:

• PEP 8 + Black formatting (double quotes, 88-char lines, 4-space indent)
• Imports ordered: standard library → third-party → local
• Type hints required, must pass Mypy

Frontend (TypeScript) - Enforced by ESLint:

• Prettier defaults (single quotes, 2-space indent, semicolons)
• Strict TypeScript, no unjustified any types
• Follow React hooks rules

Commit Message Convention

All commits must follow Conventional Commits: type: description

Type	Description	CI Behavior
feat	New feature	Triggers build/test
fix	Bug fix	Triggers build/test
refactor	Code refactoring	Triggers build/test
perf	Performance improvement	Triggers build/test
test	Add or update tests	Triggers build/test
style	Code style changes	Skips CI build
docs	Documentation only	Skips CI build
chore	Build config or tooling	Skips CI build
ci	CI/CD configuration	Skips CI build
build	Build system changes	Skips CI build
revert	Revert a previous commit	Triggers build/test

Branch Management & Pull Request

This project uses a dual main branch strategy (main for production, dev for development).

1. Branch Naming:

   • dev - Main development branch. Create feature branches from here.
   • main - Production releases only. Direct pushes prohibited.
   • Feature branches: feat/feature-name or fix/issue-description

2. Before Pull Request:

   git fetch origin
   git rebase origin/dev

3. Submission:

   • Ensure all quality checks pass locally
   • Push branch (git push --force-with-lease after rebase)
   • Create PR with target branch set to dev

4. Merge Criteria:

   • All CI checks must pass
   • Code review approval from a CODEOWNER required

Troubleshooting

Q: uv/nvm command not found?

• Restart terminal after installation. Windows: try running PowerShell as administrator.

Q: VS Code showing errors?

• Verify Python interpreter is set to backend/.venv, not system Python.

Q: Git rejecting commits?

• Pre-commit checks failed. Run uv run ruff format . and uv run ruff check . --fix, then commit again.

Q: Frontend build failing?

• Run cd frontend && npm install. If errors persist, delete node_modules and package-lock.json, then npm install.

Q: Port already in use?

lsof -i :8000  # Find process on port
kill -9 <PID>  # Kill by PID