Contributing Guide

# Fork the repository
gh repo fork sgcarstrends/backend

# Clone your fork
gh repo clone YOUR_USERNAME/backend
cd backend

# Create and switch to a new branch
git checkout -b feature/your-feature-name

# Or for bug fixes
git checkout -b fix/issue-description

# Feature
git commit -m "feat: add COE comparison analytics endpoint"

# Bug fix
git commit -m "fix: resolve authentication token validation issue"

# Documentation
git commit -m "docs: update API authentication guide"

# Breaking change
git commit -m "feat!: change API response format for consistency"

# With scope
git commit -m "feat(api): add pagination to cars endpoint"

// ✅ Good: Explicit types and error handling
export async function getCarsByMonth(
  month: string
): Promise<Car[]> {
  try {
    const result = await db
      .select()
      .from(cars)
      .where(eq(cars.month, month));
    
    return result;
  } catch (error) {
    logger.error('Failed to fetch cars', { month, error });
    throw new Error(`Failed to fetch cars for month ${month}`);
  }
}

// ✅ Good: Type guards
function isValidFuelType(fuelType: unknown): fuelType is FuelType {
  return typeof fuelType === 'string' && 
    ['Petrol', 'Diesel', 'Electric', 'Hybrid', 'Others'].includes(fuelType);
}

// ✅ Good: Proper error types
class ValidationError extends Error {
  constructor(message: string, public field: string) {
    super(message);
    this.name = 'ValidationError';
  }
}

// ✅ Good: Efficient query with proper types
export async function getCarsByMakeAndMonth(
  make: string,
  month: string
): Promise<Car[]> {
  return await db
    .select()
    .from(cars)
    .where(and(
      eq(cars.make, make),
      eq(cars.month, month)
    ))
    .orderBy(desc(cars.number));
}

// ✅ Good: Proper transaction handling
export async function updateCarData(
  carUpdates: CarUpdate[]
): Promise<void> {
  await db.transaction(async (tx) => {
    for (const update of carUpdates) {
      await tx
        .update(cars)
        .set(update)
        .where(eq(cars.id, update.id));
    }
  });
}

// ✅ Good: Error handling with database operations
export async function insertCarBatch(
  carData: NewCar[]
): Promise<Car[]> {
  try {
    return await db
      .insert(cars)
      .values(carData)
      .returning();
  } catch (error) {
    if (error instanceof Error && error.message.includes('duplicate key')) {
      throw new ValidationError('Duplicate car data', 'month,make');
    }
    throw error;
  }
}

// Unit test example
describe('calculateGrowthRate', () => {
  it('should calculate positive growth rate', () => {
    expect(calculateGrowthRate(120, 100)).toBe(20);
  });

  it('should calculate negative growth rate', () => {
    expect(calculateGrowthRate(80, 100)).toBe(-20);
  });

  it('should handle zero previous value', () => {
    expect(calculateGrowthRate(100, 0)).toBeNull();
  });

  it('should handle equal values', () => {
    expect(calculateGrowthRate(100, 100)).toBe(0);
  });
});

// Integration test example
describe('Cars API', () => {
  beforeEach(async () => {
    await setupTestDatabase();
  });

  afterEach(async () => {
    await cleanupTestDatabase();
  });

  it('should return cars for valid month', async () => {
    const response = await testClient.get('/v1/cars?month=2024-01');
    
    expect(response.status).toBe(200);
    expect(response.body.success).toBe(true);
    expect(response.body.data).toBeInstanceOf(Array);
  });
});

# Run all tests
pnpm test

# Run tests in watch mode
pnpm test:watch

# Run tests with coverage
pnpm test:coverage

# Run specific test file
pnpm test -- src/utils/__tests__/format-percentage.test.ts

/**
 * Calculates the growth rate between two values
 * @param current - The current value
 * @param previous - The previous value
 * @returns The growth rate as a percentage, or null if previous is 0
 * @example
 * ```typescript
 * const growth = calculateGrowthRate(120, 100); // Returns 20
 * ```
 */
export function calculateGrowthRate(
  current: number, 
  previous: number
): number | null {
  if (previous === 0) return null;
  return ((current - previous) / previous) * 100;
}

/**
 * Retrieves car registration data for a specific month
 * @param month - Month in YYYY-MM format
 * @throws {ValidationError} When month format is invalid
 * @throws {Error} When database query fails
 */
export async function getCarsByMonth(month: string): Promise<Car[]> {
  // Implementation
}

## Summary
Brief description of the changes made

## Type of Change
- [ ] Bug fix (non-breaking change that fixes an issue)
- [ ] New feature (non-breaking change that adds functionality)
- [ ] Breaking change (fix or feature that causes existing functionality to change)
- [ ] Documentation update
- [ ] Refactoring (no functional changes)
- [ ] Performance improvement

## Changes Made
- List specific changes
- Include any new endpoints or modified behavior
- Mention any breaking changes

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

## Documentation
- [ ] Code comments added/updated
- [ ] API documentation updated
- [ ] Examples updated
- [ ] Changelog entry added

## Related Issues
Fixes #issue_number
Relates to #issue_number

## Screenshots (if applicable)
Include screenshots for UI changes or API responses

## Checklist
- [ ] Code follows project style guidelines
- [ ] Self-review completed
- [ ] Tests added for new functionality
- [ ] Documentation updated
- [ ] No breaking changes (or properly documented)

## Bug Description
Clear description of what the bug is

## Steps to Reproduce
1. Step one
2. Step two
3. Step three

## Expected Behavior
What you expected to happen

## Actual Behavior
What actually happened

## Environment
- OS: [e.g., macOS 14.0]
- Node.js version: [e.g., 18.17.0]
- API version: [e.g., 1.6.0]

## Error Messages

## Feature Description
Clear description of the proposed feature

## Use Case
Explain why this feature would be useful

## Proposed Solution
Describe how you think this should work

## Alternatives Considered
Any alternative solutions you've considered

## Additional Context
Any other relevant information or examples

{
  "recommendations": [
    "biomejs.biome",
    "ms-vscode.vscode-typescript-next",
    "bradlc.vscode-tailwindcss",
    "ms-vscode.vscode-json",
    "redhat.vscode-yaml",
    "ms-vscode.vscode-eslint"
  ]
}

# Install husky for git hooks
pnpm add -D husky

# Set up pre-commit hook
echo "pnpm lint && pnpm test" > .husky/pre-commit
chmod +x .husky/pre-commit

# Add a changeset
pnpm changeset

# Version packages
pnpm changeset version

# Create release tags
pnpm changeset tag