Contributing Guide

Welcome to HMP development! This guide covers everything you need to contribute to the project.

Getting Started

Prerequisites

• Node.js 18.x or later
• npm or yarn
• Git
• Docker (for local development)
• PostgreSQL 14+ (or use Docker)
• Redis 7+ (or use Docker)

Setup Development Environment

1. Clone the Repository

git clone https://github.com/hmp/hmp-platform.git
cd hmp-platform

2. Install Dependencies

npm install

3. Set Up Environment Variables

cp .env.example .env

Edit .env with your local settings:

DATABASE_URL=postgresql://postgres:postgres@localhost:5432/hmp_dev
REDIS_URL=redis://localhost:6379
JWT_SECRET=dev-secret-key

4. Start Infrastructure (Docker)

docker-compose up -d postgres redis

5. Initialize Database

npm run db:migrate
npm run db:seed

6. Start Development Server

npm run dev

Branch Strategy

We follow GitFlow branching model:

main          ─────●─────────●─────────●───────
                   │         │         │
develop       ─────┼────●────┼────●────┼───────
                   │    │    │    │    │
feature/*     ─────┴────┘    │    │    │
bugfix/*      ───────────────┴────┘    │
hotfix/*      ─────────────────────────┴───────

Branch Types

Branch	Purpose	Base	Merge To
main	Production code	-	-
develop	Integration branch	main	main
feature/*	New features	develop	develop
bugfix/*	Bug fixes	develop	develop
hotfix/*	Production fixes	main	main + develop
release/*	Release preparation	develop	main + develop

Creating a Branch

# Feature branch
git checkout develop
git pull origin develop
git checkout -b feature/add-guest-preferences

# Bugfix branch
git checkout develop
git checkout -b bugfix/fix-rate-calculation

# Hotfix branch
git checkout main
git checkout -b hotfix/critical-security-fix

Commit Message Format

We use conventional commits:

<type>(<scope>): <description>

[optional body]

[optional footer]

Types

Type	Description
feat	New feature
fix	Bug fix
docs	Documentation
style	Formatting, no code change
refactor	Code restructuring
test	Adding tests
chore	Maintenance tasks

Examples

# Feature
feat(reservation): add multi-room booking support

# Bug fix
fix(pos): correct GST calculation for combo items

# Documentation
docs(api): update reservation endpoint documentation

# With body and footer
feat(channel): add Expedia integration

Implements two-way sync with Expedia:
- Availability push
- Rate push
- Booking retrieval

Closes #123

Pull Request Process

Creating a PR

1. Push Your Branch

git push origin feature/your-feature

2. Create PR on GitHub

• Title: Clear, descriptive title
• Description: Use the PR template
• Labels: Add appropriate labels
• Reviewers: Request relevant reviewers

PR Template

## Description
Brief description of changes

## Type of Change
- [ ] New feature
- [ ] Bug fix
- [ ] Breaking change
- [ ] Documentation update

## Testing
- [ ] Unit tests added/updated
- [ ] Integration tests added/updated
- [ ] Manual testing completed

## Checklist
- [ ] Code follows style guidelines
- [ ] Self-review completed
- [ ] Documentation updated
- [ ] No new warnings

Review Process

1. Automated checks run (lint, tests, build)
2. At least one approval required
3. All comments addressed
4. Squash and merge to develop

Development Workflow

Running Tests

# All tests
npm test

# Unit tests
npm run test:unit

# Integration tests
npm run test:integration

# With coverage
npm run test:coverage

Linting

# Run linter
npm run lint

# Fix auto-fixable issues
npm run lint:fix

Type Checking

npm run typecheck

Building

# Development build
npm run build:dev

# Production build
npm run build

Project Structure

hmp-platform/
├── packages/
│   ├── api/              # API Gateway
│   ├── services/
│   │   ├── auth/         # Auth service
│   │   ├── reservation/  # Reservation service
│   │   ├── guest/        # Guest service
│   │   └── ...
│   ├── shared/           # Shared utilities
│   └── ui/               # Web dashboard
├── prisma/               # Database schema
├── scripts/              # Build scripts
├── docker/               # Docker configurations
└── docs/                 # Documentation

API Development

Adding an Endpoint

1. Define route in routes.ts
2. Create handler in handlers/
3. Add validation schema
4. Write tests
5. Update API documentation

Example Handler

// handlers/reservations.ts
import { Request, Response } from 'express';
import { z } from 'zod';
import { reservationService } from '../services';

const createReservationSchema = z.object({
  guestId: z.string().uuid(),
  arrivalDate: z.string().datetime(),
  departureDate: z.string().datetime(),
  rooms: z.array(z.object({
    roomTypeId: z.string().uuid(),
    adults: z.number().min(1),
  })).min(1),
});

export async function createReservation(req: Request, res: Response) {
  const data = createReservationSchema.parse(req.body);
  const reservation = await reservationService.create(data);
  res.status(201).json({ data: reservation });
}

Database Changes

Creating Migrations

# Create migration
npm run db:migrate:create -- --name add_guest_preferences

# Run migrations
npm run db:migrate

# Rollback
npm run db:migrate:rollback

Schema Changes

1. Update Prisma schema (prisma/schema.prisma)
2. Generate migration
3. Update TypeScript types
4. Update affected services
5. Add data migration if needed

Documentation

Updating Docs

1. Edit relevant .md files in /docs
2. Run docs locally: npm run docs:dev
3. Verify changes
4. Include in PR

API Documentation

Update OpenAPI spec when changing endpoints:

# api-specs/openapi.yaml
paths:
  /reservations:
    post:
      summary: Create reservation
      # ... update specification

Getting Help

• Slack: #hmp-dev channel
• Issues: GitHub Issues for bugs
• Discussions: GitHub Discussions for questions

Related Documentation

• Coding Standards
• Testing Guide
• Deployment