Contributing

Contributing to Earthquake Catalogue Platform

Thank you for your interest in contributing to the Earthquake Catalogue Platform! This document provides guidelines and instructions for contributing.

Table of Contents

``Code of Conduct <#code-of-conduct>``_
``Getting Started <#getting-started>``_
``Development Setup <#development-setup>``_
``Development Workflow <#development-workflow>``_
``Coding Standards <#coding-standards>``_
``Testing Guidelines <#testing-guidelines>``_
``Commit Guidelines <#commit-guidelines>``_
``Pull Request Process <#pull-request-process>``_
``Issue Guidelines <#issue-guidelines>``_

Code of Conduct

Please be respectful and constructive in all interactions. We welcome contributors of all backgrounds and experience levels.

Getting Started

Prerequisites

Node.js >= 18.0.0
npm >= 9.0.0
MongoDB (local or Atlas)
Git

Development Setup

Fork and clone the repository:

`bash git clone https://github.com/KennyGraham1/catalogofcatalogs.git cd catalogofcatalogs `
Install dependencies:

`bash npm install `
Set up environment variables:

`bash cp .env.example .env.local # Edit .env.local with your configuration `
Start the development server:

`bash npm run dev `
Run tests to verify setup:

`bash npm test `

Development Workflow

Branch Naming

Use descriptive branch names following this pattern:

feature/description - New features
fix/description - Bug fixes
docs/description - Documentation updates
refactor/description - Code refactoring
test/description - Test additions or fixes

Examples: - feature/add-export-kml - fix/validation-error-handling - docs/update-api-docs

Local Development

Create a new branch from main:

`bash git checkout main git pull origin main git checkout -b feature/your-feature `
Make your changes following the coding standards.
Write or update tests as needed.
Run the test suite:

`bash npm test `
Run linting:

`bash npm run lint `
Check TypeScript:

`bash npx tsc --noEmit `

Coding Standards

TypeScript

Use TypeScript for all new code
Enable strict mode
Avoid any types - use proper interfaces
Use meaningful variable and function names
Add JSDoc comments for public functions

// Good
interface EarthquakeEvent {
  id: string;
  time: string;
  latitude: number;
  longitude: number;
  magnitude: number;
  depth?: number;
}

function calculateDistance(
  lat1: number,
  lon1: number,
  lat2: number,
  lon2: number
): number {
  // Implementation
}

// Avoid
function calc(a: any, b: any): any {
  // ...
}

React Components

Use functional components with hooks
Use TypeScript interfaces for props
Keep components focused and small
Use 'use client' directive only when necessary

// Good
interface ButtonProps {
  label: string;
  onClick: () => void;
  variant?: 'primary' | 'secondary';
  disabled?: boolean;
}

export function Button({ label, onClick, variant = 'primary', disabled }: ButtonProps) {
  return (
    <button
      className={cn('btn', variant === 'primary' ? 'btn-primary' : 'btn-secondary')}
      onClick={onClick}
      disabled={disabled}
    >
      {label}
    </button>
  );
}

File Organization

app/                    # Next.js App Router pages
  api/                  # API routes
  (auth)/               # Auth route group
components/             # React components
  ui/                   # shadcn/ui components
  [feature]/            # Feature-specific components
lib/                    # Utility functions and modules
types/                  # TypeScript type definitions
hooks/                  # Custom React hooks
contexts/               # React context providers
__tests__/              # Test files

Styling

Use Tailwind CSS for styling
Use the cn() utility for conditional classes
Follow the existing design system

Testing Guidelines

Test Structure

describe('ModuleName', () => {
  describe('functionName', () => {
    it('should handle the expected case', () => {
      // Arrange
      const input = {...};

      // Act
      const result = functionName(input);

      // Assert
      expect(result).toBe(expected);
    });

    it('should handle edge cases', () => {
      // ...
    });

    it('should throw on invalid input', () => {
      expect(() => functionName(null)).toThrow();
    });
  });
});

Test Coverage

Aim for 70%+ coverage on new code
Critical modules (validation, auth) should have 80%+ coverage
Write tests for: - Happy path scenarios - Edge cases - Error conditions - Security-sensitive code

Running Tests

# Run all tests
npm test

# Run tests in watch mode
npm run test:watch

# Run tests with coverage
npm run test:coverage

# Run specific test file
npm test -- path/to/test.test.ts

Commit Guidelines

Commit Message Format

Follow the Conventional Commits specification:

type(scope): subject

body

footer

Types: - feat: New feature - fix: Bug fix - docs: Documentation changes - style: Code style changes (formatting, etc.) - refactor: Code refactoring - test: Test additions or fixes - chore: Maintenance tasks

Examples:

feat(upload): add support for QuakeML 1.2 format

- Parse QuakeML 1.2 XML structure
- Extract origin and magnitude information
- Handle nested event elements

Closes #123

fix(validation): correct latitude range check

The validation was incorrectly rejecting valid latitudes
near the poles due to floating-point precision issues.

Fixes #456

Pre-commit Checks

The project uses Husky for pre-commit hooks. Before each commit:

Tests run for changed files
Linting is verified
TypeScript types are checked

If any check fails, fix the issues before committing.

Pull Request Process

Before Submitting

✅ All tests pass (npm test)
✅ Linting passes (npm run lint)
✅ TypeScript compiles (npx tsc --noEmit)
✅ Code follows the project style
✅ Documentation is updated if needed
✅ Commit messages follow guidelines

PR Description Template

## Summary

Brief description of the changes.

## Changes

- List of specific changes
- Another change
- ...

## Testing

Describe how you tested the changes.

## Screenshots (if applicable)

Add screenshots for UI changes.

## Related Issues

Fixes #123
Relates to #456

Review Process

Submit the PR with a clear description
Address any automated check failures
Respond to reviewer feedback
Make requested changes in new commits
Once approved, the PR will be merged

Issue Guidelines

Bug Reports

Include: - Clear description of the bug - Steps to reproduce - Expected vs actual behavior - Browser/environment details - Screenshots if applicable

Feature Requests

Include: - Clear description of the feature - Use case / motivation - Proposed implementation (if any) - Alternatives considered

Questions

For questions, consider: - Checking existing documentation - Searching closed issues - Creating a discussion (if enabled)

Getting Help

Review existing documentation
Check the issue tracker
Create a new issue for bugs or features

Thank you for contributing! 🎉