Contributing to Elite Events

Thank you for contributing to Elite Events! This document provides guidelines and best practices for contributing to the project.

📋 Table of Contents

• Code of Conduct
• Getting Started
• Development Workflow
• Code Standards
• Commit Guidelines
• Testing Requirements
• Documentation
• Pull Request Process
• Review Process

Code of Conduct

Our Pledge

We are committed to providing a welcoming and inclusive environment for all contributors.

Expected Behavior

• Be respectful and professional
• Accept constructive criticism gracefully
• Focus on what is best for the project
• Show empathy towards others

Unacceptable Behavior

• Harassment or discrimination
• Trolling or insulting comments
• Publishing private information
• Unprofessional conduct

Getting Started

Prerequisites

1. Read the Documentation

   • Quickstart Guide
   • Development Guide
   • Project Status

2. Setup Development Environment

   git clone <repository-url>
   cd elite_events_nextjs
   
   # Automated setup (recommended)
   npm run setup
   
   # Or manual setup
   npm install
   

3. Configure Environment

   • The setup script will create .env from .env.example
   • Update database credentials
   • Add required API keys

4. Verify Setup

   npm run dev          # Start dev server
   npm test             # Run tests
   npm run lint         # Run linter
   

Development Tools

Use built-in generators to scaffold new code:

# Generate a new component with tests and Storybook story
npm run generate:component Button --ui
npm run generate:component ProductCard --feature

# Generate a new API route with tests
npm run generate:api products
npm run generate:api users/[id] --admin

Development Workflow

1. Create a Branch

# Update main branch
git checkout main
git pull origin main

# Create feature branch
git checkout -b feature/your-feature-name

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

Branch Naming Conventions

• feature/ - New features
• fix/ - Bug fixes
• refactor/ - Code refactoring
• docs/ - Documentation updates
• test/ - Test additions/modifications
• chore/ - Maintenance tasks

2. Make Changes

• Write clean, readable code
• Follow existing code patterns
• Add comments for complex logic
• Update documentation as needed

3. Test Your Changes

# Run tests
npm test

# Run specific test
npm test -- your-test-file.test.ts

# Check coverage
npm run test:coverage

# Type check
npm run type-check

# Lint
npm run lint

4. Commit Your Changes

See Commit Guidelines below.

5. Push and Create Pull Request

# Push to remote
git push origin feature/your-feature-name

# Create PR via GitHub UI

Code Standards

TypeScript

• Use TypeScript for all new code
• Define proper types (avoid any)
• Use interfaces for object shapes
• Export types from dedicated files

// ✅ Good
interface Product {
  id: number;
  title: string;
  price: number;
}

// ❌ Bad
const product: any = {...};

React Components

• Use functional components with hooks
• Extract complex logic into custom hooks
• Use proper prop typing
• Keep components focused and small

// ✅ Good
interface ProductCardProps {
  product: Product;
  onAddToCart: (id: number) => void;
}

export function ProductCard({ product, onAddToCart }: ProductCardProps) {
  // Component logic
}

// ❌ Bad
export function ProductCard(props: any) {
  // Component logic
}

File Naming

• Components: PascalCase.tsx (e.g., ProductCard.tsx)
• Utilities: kebab-case.ts (e.g., format-price.ts)
• Types: PascalCase.ts (e.g., Product.ts)
• Tests: kebab-case.test.ts (e.g., format-price.test.ts)

Code Organization

src/
├── components/
│   └── features/
│       └── shop/
│           └── ProductCard/
│               ├── index.tsx           # Main component
│               ├── ProductCard.module.css
│               └── __tests__/
│                   └── ProductCard.test.tsx

Styling

• Use Tailwind CSS for utility classes
• Use CSS Modules for component-specific styles
• Follow mobile-first approach
• Maintain consistent spacing (4px grid)

// ✅ Good
<div className="flex gap-4 p-4 md:p-6">
  <ProductCard />
</div>

// ❌ Bad
<div style={{ display: 'flex', gap: '16px' }}>
  <ProductCard />
</div>

API Routes

• Use proper HTTP methods (GET, POST, PUT, DELETE)
• Validate input with Zod schemas
• Return consistent response format
• Handle errors gracefully

// ✅ Good
export async function POST(req: NextRequest) {
  try {
    const body = await req.json();
    const validated = schema.parse(body);

    // ... logic

    return NextResponse.json({ success: true, data });
  } catch (error) {
    return NextResponse.json(
      { error: 'Invalid request' },
      { status: 400 }
    );
  }
}

Commit Guidelines

Commit Message Format

Type: Brief description (50 chars max)

Detailed explanation if needed (wrap at 72 chars).
Can span multiple lines.

Fixes #123

Types

• Add: - New feature
• Fix: - Bug fix
• Update: - Update existing feature
• Refactor: - Code refactoring
• Docs: - Documentation changes
• Test: - Test additions/modifications
• Chore: - Maintenance tasks
• Style: - Code style changes (formatting)
• Perf: - Performance improvements

Examples

# ✅ Good
git commit -m "Add: product comparison feature"
git commit -m "Fix: cart quantity update not persisting"
git commit -m "Update: improve search performance"

# ❌ Bad
git commit -m "updated stuff"
git commit -m "fix bug"
git commit -m "WIP"

Commit Best Practices

• One logical change per commit
• Write clear, descriptive messages
• Reference issue numbers when applicable
• Don't commit broken code
• Keep commits atomic and focused

Testing Requirements

Test Coverage

• Critical features (auth, cart, checkout): 90%+
• Utilities: 85%+
• Components: 70%+
• Overall: 60%+

Types of Tests

Unit Tests

Test individual functions and utilities.

describe('formatPrice', () => {
  it('should format price with dollar sign', () => {
    expect(formatPrice(100)).toBe('$100.00');
  });
});

Component Tests

Test React components in isolation.

describe('ProductCard', () => {
  it('should render product title', () => {
    render(<ProductCard product={mockProduct} />);
    expect(screen.getByText('Test Product')).toBeInTheDocument();
  });
});

Integration Tests

Test feature workflows end-to-end.

describe('Add to Cart Flow', () => {
  it('should add product to cart and update count', async () => {
    // ... test workflow
  });
});

Before Submitting PR

# All tests must pass
npm test

# No linting errors
npm run lint

# No type errors
npm run type-check

# Successful build
npm run build

Documentation

When to Update Docs

• Adding new features
• Changing API endpoints
• Modifying configuration
• Updating dependencies
• Changing workflows

Documentation Standards

• Use clear, concise language
• Include code examples
• Add screenshots for UI changes
• Update relevant guides
• Keep README up to date

Documentation Files

docs/
├── QUICKSTART.md        # Update for setup changes
├── API_REFERENCE.md     # Update for API changes
├── guides/
│   ├── DEVELOPMENT.md   # Update for architecture changes
│   └── TESTING.md       # Update for testing changes
└── CHANGELOG.md         # Add entry for all changes

Pull Request Process

Before Creating PR

1. ✅ Code Complete

   • Feature fully implemented
   • Tests written and passing
   • No linting errors
   • No TypeScript errors

2. ✅ Documentation Updated

   • Code comments added
   • README updated (if needed)
   • CHANGELOG.md updated
   • API_REFERENCE updated (if API changed)

3. ✅ Tests Passing

   npm test
   npm run lint
   npm run type-check
   npm run build
   

4. ✅ Branch Updated

   git checkout main
   git pull origin main
   git checkout your-branch
   git rebase main
   

PR Template

## Description
Brief description of changes

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

## Changes Made
- Change 1
- Change 2
- Change 3

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

## Documentation
- [ ] Code comments added
- [ ] README updated
- [ ] CHANGELOG updated
- [ ] API docs updated

## Screenshots (if applicable)
[Add screenshots here]

## Related Issues
Fixes #123
Closes #456

PR Checklist

• Branch is up to date with main
• All tests passing
• No linting errors
• No TypeScript errors
• Documentation updated
• CHANGELOG.md updated
• Meaningful commit messages
• PR description complete

Review Process

For PR Authors

1. Respond to feedback promptly and professionally
2. Make requested changes or provide reasoning
3. Update PR as needed
4. Re-request review after changes

For Reviewers

1. Review promptly (within 24-48 hours)
2. Be constructive in feedback
3. Test the changes locally if possible
4. Approve or request changes clearly

Review Checklist

• Code follows project standards
• Tests are comprehensive
• Documentation is clear
• No unnecessary changes
• Performance considerations
• Security implications addressed
• Accessibility maintained

Best Practices

Do's ✅

• Write self-documenting code
• Keep functions small and focused
• Use meaningful variable names
• Handle errors gracefully
• Write tests for new features
• Update documentation
• Follow existing patterns
• Ask questions when unclear

Don'ts ❌

• Don't commit sensitive data (API keys, passwords)
• Don't commit commented-out code
• Don't commit console.log statements
• Don't push directly to main
• Don't skip testing
• Don't ignore linting errors
• Don't make massive PRs (keep them focused)

Getting Help

Resources

• Documentation
• Development Guide
• API Reference
• Troubleshooting

Additional Guides

• Hook Development
• Redux Patterns
• API Route Checklist
• Validation Guide
• Query Optimization

Communication

• Questions: Open a GitHub Discussion
• Bugs: Create an Issue
• Features: Create an Issue with [FEATURE] tag
• Urgent: Contact team lead

License

By contributing, you agree that your contributions will be licensed under the same license as the project.

Thank you for contributing to Elite Events! 🎉

Every contribution, no matter how small, helps make this project better.