Skip to content

Latest commit

 

History

History
234 lines (168 loc) · 6.64 KB

CONTRIBUTING.md

File metadata and controls

234 lines (168 loc) · 6.64 KB

Contributing to PathFinder

Thank you for your interest in contributing to PathFinder! This guide explains how to set up your environment, follow our workflows, and ship high-quality changes.

Development Setup

Prerequisites

  • Python 3.11 or higher
  • Node.js 18+ (Node 20 recommended) and npm
  • Optional: PostgreSQL 15+ if you prefer not to use SQLite during development
  • Access to the SAS Google Workspace OAuth client and OpenAI credentials (for features that depend on them)

Quick Start

  1. Clone the repository

    git clone https://github.com/YianXie/path-finder.git
cd path-finder

  2. Set up the backend

    cd backend
uv venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate
uv sync
# Create backend/.env based on the Environment Variables section
python manage.py migrate

  3. Set up the frontend

    cd frontend
npm install
# Create .env.local (or .env) based on the Environment Variables section
cd ..

  4. Run the development servers

    # terminal 1 (from backend directory)
cd backend
source .venv/bin/activate  # if not already active
python manage.py runserver

# terminal 2 (from frontend directory)
cd frontend
npm run dev

The API runs on http://localhost:8000 and the web app on http://localhost:5173.

One-command installs

Prefer automation? From the repository root:

make install     # install backend + frontend dependencies
make ci-local    # run the same checks as CI

See Makefile for the full list of commands.

Code Quality Standards

Before Submitting Code

Always run our CI-equivalent checks locally:

make ci-local
# or
./scripts/ci-local.sh

Formatting

  • Backend: Ruff formatter (Black-compatible) and isort import ordering
  • Frontend: Prettier with Tailwind and import sort plugins
make format

Linting

  • Backend: ruff check for linting, security linting via Bandit
  • Frontend: ESLint with React and hooks plugins
make lint

Testing

  • Backend: Django test suite (python manage.py test from backend/ directory)
  • Frontend: Vite build verification (npm run build from frontend/ directory)
make test

Security Checks

  • Backend: Safety vulnerability scan, Bandit static analysis
  • Frontend: npm audit
make security

Pull Request Process

  1. Create a focused branch

    git checkout -b feature/my-improvement

  2. Implement changes

    • Add or update tests where applicable
    • Update documentation or config changes as needed
    • Keep commits scoped and descriptive

  3. Run local checks

    make ci-local

  4. Commit with context

    git add .
git commit -m "feat: describe the change"

  5. Push and open a PR

    git push origin feature/my-improvement

In your PR description, summarize the change, list test coverage, and call out any follow-up work.

GitHub Actions CI

We run CI on every push to main and every pull request. Current jobs include:

  1. Backend tests – Django test suite against PostgreSQL service
  2. Backend linting – Ruff lint, format check, Bandit
  3. Frontend checks – ESLint, Prettier format check, Vite build
  4. Security – Safety scan and dependency review

PRs also report code coverage and dependency alerts when applicable.

Environment Variables

Configure environment variables before running servers or tests.

Backend (backend/.env):

ENVIRONMENT=""  # the environment where your backend is running, for local development, use 'development'
SECRET_KEY=""  # your Django secret_key, can be re-generated if needed
ALLOWED_HOSTS=""  # your domain (without https:// or http://)
CORS_ALLOWED_ORIGINS=""  # your domain (with https:// or http://)
CSRF_TRUSTED_ORIGINS=""  # your domain (with https:// or http://)
DATABASE_URL=""  # the url to access your PostgreSQL database
CLOUDINARY_CLOUD_NAME=""  # Your Cloudinary Cloud Name, can be found on the Cloudinary website
CLOUDINARY_API_KEY=""  # Your Cloudinary API Key, can be found on the Cloudinary website
CLOUDINARY_API_SECRET=""  # Your Cloudinary API Secret, can be found on the Cloudinary website
GOOGLE_CLIENT_ID=""  # your Google Client ID for google login (should match with frontend)
ALLOWED_GOOGLE_HD=""  # (optional) only allow specific email address domain to login (e.g., your-company.com)
SHEET_ID=""  # the Google Spreadsheet ID, can be found in the url of the sheet, sheet must be set to publicly visible
OPENAI_API_KEY=""  # your OpenAI API Key, can be found on the OpenAI website

Frontend (frontend/.env):

VITE_ENVIRONMENT=""  # the environment (default is 'development')
VITE_API_URL=""  # the url where you backend (Django Rest Framework) runs
VITE_GOOGLE_CLIENT_ID=""  # your Google Client's ID (should match with backend)

Never commit secrets—use .env.local overrides or your deployment platform’s secret manager.

Project Structure

path-finder/
├── backend/
│   ├── accounts/                # Google OAuth, profile management, saved items
│   ├── social/                  # Ratings and reviews APIs
│   ├── suggestions/             # Suggestion models, ingestion, LLM personalization
│   │   └── management/commands/ # sync_sheet, add_missing_tags, etc.
│   ├── pathfinder_api/          # Django settings, urls, ASGI/WSGI
│   └── pyproject.toml           # Dependencies managed via uv
├── frontend/
│   ├── src/
│   │   ├── components/
│   │   ├── contexts/
│   │   ├── hooks/
│   │   └── pages/
│   ├── public/
│   ├── package.json
│   └── vite.config.js
├── scripts/                     # CI helpers
├── Makefile                     # Project-wide tasks
├── .github/                     # GitHub Actions workflows & docs
└── README.md

Getting Help

Code of Conduct

We strive for a welcoming, collaborative community. Please be respectful and constructive in discussions and reviews.

License

By contributing to PathFinder you agree that your contributions are provided under the MIT License.