Skip to content

Latest commit

 

History

History
202 lines (138 loc) · 5.06 KB

CONTRIBUTING.md

File metadata and controls

202 lines (138 loc) · 5.06 KB

Contributing to E-commerce Store API

First off, thank you for considering contributing to this project! 🎉

Whether it's a bug report, new feature, correction, or additional documentation, your contributions are greatly appreciated.

Table of Contents

Code of Conduct

This project adheres to a Code of Conduct. By participating, you are expected to uphold this code.

Getting Started

  1. Fork the repository on GitHub
  2. Clone your fork locally: 
    git clone https://github.com/YOUR_USERNAME/ecommerce-store-api.git
cd ecommerce-store-api
  3. Add the upstream repository as a remote: 
    git remote add upstream https://github.com/raouf-b-dev/ecommerce-store-api.git

Development Setup

Prerequisites

  • Node.js ≥ 22
  • npm ≥ 11
  • Docker Desktop ≥ 28
  • Git ≥ 2.49

Installation

# Install dependencies
npm install

# Generate environment files
npm run env:init:dev

# Start infrastructure services (PostgreSQL, Redis)
npm run d:up:dev

# Run database migrations
npm run migration:run:dev

# Start development server
npm run start:dev

The API will be available at http://localhost:3000 with Swagger docs at http://localhost:3000/api.

Making Changes

  1. Create a new branch from develop:

    git checkout -b feature/your-feature-name
# or
git checkout -b fix/your-bug-fix

  2. Make your changes following our code style guidelines

  3. Write or update tests for your changes

  4. Run the test suite to ensure everything passes:

    npm test

  5. Commit your changes with a clear message:

    git commit -m "Add: brief description of your change"

Commit Message Guidelines

We follow a simple commit convention:

  • Add: for new features
  • Fix: for bug fixes
  • Update: for changes to existing features
  • Refactor: for code refactoring
  • Docs: for documentation changes
  • Test: for test-related changes

Code Style

This project uses ESLint and Prettier to maintain code quality. Before committing:

# Run linter with auto-fix
npm run lint

# Check formatting
npm run format:check

# Fix formatting
npm run format

Architecture Guidelines

This project follows Domain-Driven Design (DDD) and Hexagonal Architecture (Ports & Adapters). Please ensure:

  • Core (core/domain/): Pure business logic — entities, value objects, repository interfaces. Zero external dependencies.
  • Core (core/application/): Use cases that orchestrate domain logic. Depends only on Domain.
  • Primary Adapters (primary-adapters/): Driving adapters — DTOs, job handlers, event listeners. NestJS Controllers live at the module root and inject Use Cases directly (no intermediate controller classes).
  • Secondary Adapters (secondary-adapters/): Driven adapters — repository implementations, ORM entities, mappers, external service integrations.
  • Shared Kernel (src/shared-kernel/): Cross-cutting infrastructure (database, Redis, jobs, error types, interceptors).

Testing

We maintain high test coverage. Please include tests for any new functionality:

# Run all tests
npm test

# Run tests in watch mode
npm run test:watch

# Check coverage
npm run test:cov

Test Location

  • Unit tests should be co-located with the code they test (e.g., usecase.spec.ts next to usecase.ts)
  • Use the testing/ folder within each module for test utilities and factories

Submitting a Pull Request

  1. Update your fork with the latest upstream changes:

    git fetch upstream
git rebase upstream/master

  2. Push your branch to your fork:

    git push origin feature/your-feature-name

  3. Create a Pull Request on GitHub with:

    • A clear title describing the change
    • A description of what changed and why
    • Reference any related issues (e.g., "Fixes #123")

  4. Wait for review - maintainers will review your PR and may request changes

PR Checklist

  • Code follows the project's style guidelines
  • Tests pass locally (npm test)
  • New functionality includes appropriate tests
  • Documentation is updated if needed
  • Commit messages are clear and descriptive

Issue Reporting

Bug Reports

When reporting bugs, please include:

  • A clear, descriptive title
  • Steps to reproduce the issue
  • Expected vs actual behavior
  • Your environment (Node.js version, OS, etc.)
  • Any relevant logs or screenshots

Feature Requests

For feature requests, please describe:

  • The problem you're trying to solve
  • Your proposed solution
  • Any alternative solutions you've considered

Questions?

Feel free to open an issue for any questions or discussions. We're happy to help!

Thank you for contributing! 🙏