diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index e69de29..3733c51 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -0,0 +1,347 @@ +# Contributing to Fashio + +Thank you for contributing to Fashio. This document outlines the development standards, workspace architecture, issue tracking protocol, and pull request workflow required for maintaining a structured open-source codebase. + +--- + +## Table of Contents + +1. [Code of Conduct](#code-of-conduct) +2. [Monorepo Architecture & Rules](#monorepo-architecture--rules) +3. [Functional Team Clusters](#functional-team-clusters) +4. [Issue Labeling Strategy](#issue-labeling-strategy) +5. [Development Environment Setup](#development-environment-setup) +6. [Branching & Development Workflow](#branching--development-workflow) +7. [Coding & Quality Verification](#coding--quality-verification) +8. [Commit Message Specification](#commit-message-specification) +9. [Submitting a Pull Request](#submitting-a-pull-request) +10. [Milestone Roadmap Summary](#milestone-roadmap-summary) + +--- + +## Code of Conduct + +All contributors are expected to uphold a professional, respectful, and inclusive environment. Discriminatory behavior, harassment, or non-constructive communication will not be tolerated. + +--- + +## Monorepo Architecture & Rules + +The project operates as a decoupled monorepo containing a Django REST Framework backend managed by `uv` and a React frontend built with Vite. + +```text +fashio/ +├── .github/ +│ ├── ISSUE_TEMPLATE/ +│ │ ├── bug_report.md +│ │ └── feature_request.md +│ ├── workflows/ +│ │ ├── backend-ci.yml +│ │ └── frontend-ci.yml +│ └── PULL_REQUEST_TEMPLATE.md +│ +├── backend/ # Django REST Framework application (managed by uv) +│ ├── .python-version # Python version pinned by uv +│ ├── pyproject.toml # Dependencies and tool settings managed by uv +│ ├── uv.lock # Deterministic dependency lockfile +│ ├── Dockerfile +│ ├── manage.py +│ ├── config/ # Core Django settings and URLs +│ │ ├── __init__.py +│ │ ├── asgi.py +│ │ ├── urls.py +│ │ ├── wsgi.py +│ │ └── settings/ +│ │ ├── __init__.py +│ │ ├── base.py +│ │ ├── local.py +│ │ └── prod.py +│ └── apps/ # Modular Django domain applications +│ ├── __init__.py +│ ├── authentication/ +│ ├── catalog/ +│ ├── orders/ +│ ├── profiles/ +│ └── sellers/ +│ +├── frontend/ # React single-page application (Vite) +│ ├── .eslintrc.cjs +│ ├── .prettierrc +│ ├── package.json +│ ├── vite.config.js +│ ├── Dockerfile +│ └── src/ +│ ├── components/ # Reusable UI primitives (Buttons, Modals) +│ ├── context/ # React Context providers +│ ├── features/ # Domain-specific UI and state logic +│ │ ├── auth/ +│ │ ├── catalog/ +│ │ ├── cart/ +│ │ └── checkout/ +│ ├── layouts/ # Page shell layouts +│ ├── pages/ # Route views +│ ├── services/ # API interaction layer +│ └── store/ # State management store +│ +├── compose.yml # Container orchestration specification +├── .env.example +├── ARCHITECTURE.md +├── CONTRIBUTING.md +└── README.md +``` + +### Workspace Execution Rules + +* **Backend Environment (`uv`):** All Python interactions must use `uv`. Dependencies are synced via `uv sync`, and scripts/management commands must execute using `uv run python manage.py `. +* **Modular Django Apps:** All domain logic resides inside `/backend/apps/`. The settings configuration inserts `/backend/apps/` into `sys.path` to permit direct application imports (e.g., `from catalog.models import Product`). +* **Modular Settings:** Environment configuration is divided within `config/settings/` (`base.py`, `local.py`, `prod.py`) using `django-environ` for secret isolation. +* **Frontend Component Architecture:** Primitive, generic UI components belong in `src/components/`, while domain-specific state, API service calls, and sub-views must be placed inside `src/features//`. + +--- + +## Functional Team Clusters + +To avoid merge bottlenecks across contributor teams, tasks are organized into three primary functional domain clusters: + +* **Cluster A (Core & Identity):** Covers Milestone 0 (Infrastructure), Milestone 1 (Auth & Identity), and Milestone 6 (Customer Profiles & History). +* **Cluster B (Catalog & Vendor Engine):** Covers Milestone 2 (Catalog & Product Engine), Milestone 3 (Seller/Vendor Management), and Milestone 7 (Global UI Navigation & Search). +* **Cluster C (Commerce & Operations):** Covers Milestone 4 (Cart & Wishlist), Milestone 5 (Checkout & Orders), and Milestone 8 (Security, Hardening & Launch). + +--- + +## Issue Labeling Strategy + +All backlog tasks and pull requests must be classified using three label categories: + +### 1. Layer Classification +* `layer:backend/drf` +* `layer:frontend/react` +* `layer:database` +* `layer:devops` +* `layer:docs` +* `layer:design/ui` + +### 2. Type Classification +* `type:feat` +* `type:fix` +* `type:refactor` +* `type:test` +* `type:security` + +### 3. Complexity Estimation +* `good-first-issue` (1–2 Story Points) +* `complexity:medium` (3–5 Story Points) +* `complexity:complex` (8+ Story Points) + +--- + +## Development Environment Setup + +### Prerequisites + +* Python >= 3.12 +* [uv](https://github.com/astral-sh/uv) package manager +* Node.js >= 20.0.0 +* Podman / Docker Engine with Compose support + +### Setup Steps + +1. Fork the repository on GitHub and clone your fork locally: +```bash + git clone [https://github.com/YOUR_USERNAME/Fashio.git](https://github.com/YOUR_USERNAME/Fashio.git) + cd Fashio +``` + +2. Configure the upstream remote repository: +```bash +git remote add upstream [https://github.com/ORIGINAL_OWNER/Fashio.git](https://github.com/ORIGINAL_OWNER/Fashio.git) +``` + + +3. Initialize environment configuration: +```bash +cp .env.example .env +``` + + +4. Launch the local container environment using Podman or Docker: +```bash +# Using Podman +podman compose up --build + +# Using Docker +docker compose up --build +``` + +Application addresses: + +* Backend API: `http://localhost:8000` +* Frontend Application: `http://localhost:5173` +* PostgreSQL Database: `localhost:5432` + +--- + +## Branching & Development Workflow + +Do not commit directly to `main` or `dev`. All work must occur on dedicated feature branches. + +1. Fetch and rebase against upstream tracking branch: +```bash +git fetch upstream +git checkout -b / upstream/main +``` + +2. Keep branches small and focused on a single issue. + +### Branch Prefix Naming + +* `feat/` - New functionality +* `fix/` - Bug fixes +* `docs/` - Documentation modifications +* `refactor/` - Code changes that do not alter behavior +* `test/` - Adding or updating test suites +* `ci/` - Pipeline configuration changes + +--- + +## Coding & Quality Verification + +Before committing, run local verification checks. + +### Backend Validation (`/backend`) + +```bash +cd backend + +# Sync environment +uv sync + +# Static analysis and linting +uv run ruff check . + +# Validate formatting +uv run ruff format --check . + +# Execute test suite +uv run pytest +``` + +Automated code formatting can be applied using: + +```bash +uv run ruff format . + +``` + +### Frontend Validation (`/frontend`) + +```bash +cd frontend + +# Install dependencies +npm install + +# Run linter +npm run lint + +# Validate production build compilation +npm run build +``` + +--- + +## Commit Message Specification + +Commits must conform to the [Conventional Commits](https://www.conventionalcommits.org/) specification: + +```text +(): + +[optional detailed description] + +[optional issue reference] + +``` + +### Supported Types + +* `feat`: A new feature implementation +* `fix`: A bug resolution +* `docs`: Documentation-only updates +* `style`: White-space, formatting, or missing semi-colon fixes +* `refactor`: Code restructures that do not alter public API behavior +* `perf`: Performance optimizations +* `test`: Adding or correcting tests +* `chore`: Build process or tooling updates + +### Example Commit Message + +```text +feat(auth): implement Google OAuth2 token exchange endpoint + +Integrate ID token validation flow for frontend authentication calls. +Includes unit test coverage for user creation and JWT pair issuance. + +Closes #19 + +``` + +--- + +## Submitting a Pull Request + +1. Rebase your feature branch onto the latest upstream branch: +```bash +git fetch upstream +git rebase upstream/main + +``` + + +2. Push your topic branch to your fork: +```bash +git push -u origin / + +``` + + +3. Open a Pull Request on GitHub against the target branch (`main` or `dev`). +4. Ensure your PR description clearly states: +* The issue being addressed. +* A summary of technical changes. +* Steps required to manually verify the implementation. + + +5. Verify that all GitHub Actions CI status checks pass cleanly. + +--- + +## Milestone Roadmap Summary + +The roadmap is structured into 8 sequential milestones containing granular implementation tasks: + +* **Milestone 0: Environment, CI/CD & Architecture Setup:** Repository initialization, containerization, quality pipelines, and project documentation. + + +* **Milestone 1: Authentication & Identity Management:** JWT pair issuance, registration, password recovery, and Google/GitHub OAuth integrations. + + +* **Milestone 2: Catalog, Categories & Product Engine:** Hierarchical categories (`mptt`), product models, full-text search, filtering, and catalog UI. + + +* **Milestone 3: Seller Management & Vendor System:** Vendor profiles, seller authorization rules (`IsSeller`), and product management dashboards. + + +* **Milestone 4: Cart & Wishlist System:** Session-based and persistent user carts, cart synchronization, and wishlist persistence. + + +* **Milestone 5: Checkout Engine & Order Flow:** Atomic order transactions, inventory locking, state transitions, and payment processing integrations. + + +* **Milestone 6: Customer Profile, Reviews & History:** User settings, address management, order history, and verified purchase product reviews. + + +* **Milestone 7: Global UI Navigation, Search & Layout:** App layout shells, debounced global search, toast notifications, and responsive navigation. + + +* **Milestone 8: Hardening, Security, Performance & Launch:** DRF throttling, database indexing, OpenAPI documentation generation, and E2E testing.