mirror_match/CONTRIBUTING.md

Contributing to MirrorMatch

Thank you for your interest in contributing to MirrorMatch! This document outlines the coding conventions, development workflow, and expectations for contributors.

Getting Started

Local Development Setup

1. Clone the repository (if applicable) or navigate to the project directory

2. Install dependencies:

   npm install
   

3. Set up environment variables:

   • Copy env.example to .env
   • Configure DATABASE_URL, NEXTAUTH_SECRET, and email settings
   • See README.md for detailed setup instructions

4. Set up the database:

   npm run db:generate
   npm run db:migrate
   npm run db:seed
   

5. Start the development server:

   npm run dev
   

6. Open the app:

   • Navigate to http://localhost:3000
   • Login with default admin: admin@mirrormatch.com / admin123

Coding Conventions

TypeScript

• Use TypeScript for all code - no JavaScript files
• Strict mode enabled - follow TypeScript best practices
• Avoid any types - use proper types or unknown when necessary
• Define types explicitly - don't rely on type inference when it reduces clarity

Code Style

• Follow existing patterns - maintain consistency with the codebase
• Use meaningful names - variables, functions, and components should be self-documenting
• Keep functions focused - single responsibility principle
• Prefer small components - break down large components into smaller, composable pieces

Folder Structure

Follow the established structure:

app/              # Next.js App Router routes
components/       # Reusable React components
lib/             # Utility functions and helpers
prisma/           # Database schema and migrations
types/            # TypeScript type definitions

Naming Conventions

• Components: PascalCase (e.g., Navigation.tsx, GuessForm.tsx)
• Files: Match component/function names (e.g., lib/utils.ts)
• Variables/Functions: camelCase (e.g., getUserById, photoUrl)
• Constants: UPPER_SNAKE_CASE (e.g., MAX_POINTS)
• Types/Interfaces: PascalCase (e.g., User, PhotoData)

Linting and Formatting

• ESLint is configured - run npm run lint to check for issues
• Fix linting errors before committing
• Follow Next.js ESLint rules - the project uses eslint-config-next

Development Workflow

Before Making Changes

1. Read the documentation:

   • README.md - Project overview and setup
   • ARCHITECTURE.md - System design and data flows
   • .cursor/rules/mirrormatch.mdc - Project rules and guidelines
   • CONTRIBUTING.md (this file) - Coding conventions
   • SECURITY.md - Security practices

2. Understand the codebase:

   • Review related files before modifying
   • Understand the data model in prisma/schema.prisma
   • Check existing patterns for similar features

3. Plan your changes:

   • Break down large changes into smaller, incremental steps
   • Consider impact on existing features
   • Think about security implications

Making Changes

1. Create a focused change:

   • One feature or fix per commit when possible
   • Keep changes small and reviewable
   • Test your changes locally

2. Follow established patterns:

   • Use existing component patterns
   • Follow the same structure for new API routes
   • Maintain consistency with existing code style

3. Write clear code:

   • Add comments for complex logic
   • Use descriptive variable names
   • Keep functions and components focused

Adding New Features

When adding new features:

1. Update documentation:

   • Update README.md if user-facing behavior changes
   • Update ARCHITECTURE.md if system design changes
   • Update .cursor/rules/mirrormatch.mdc if rules change
   • Update SECURITY.md if security practices change

2. Follow security guidelines:

   • Validate all user inputs
   • Check authorization for all mutations
   • Never expose sensitive data
   • See SECURITY.md for details

3. Test your changes:

   • Test the feature manually
   • Verify error handling
   • Check edge cases
   • Ensure no regressions

4. Update types:

   • Add TypeScript types for new data structures
   • Update Prisma schema if database changes needed
   • Run npm run db:generate after schema changes

Commit Messages

Write clear, descriptive commit messages:

• Format: Use imperative mood (e.g., "Add photo upload validation")
• Be specific: Describe what changed and why
• Reference issues: If applicable, reference issue numbers

Examples:

• ✅ "Add password strength validation to change password form"
• ✅ "Fix case-insensitive guess matching bug"
• ✅ "Update README with new environment variables"
• ❌ "Fixed stuff"
• ❌ "Updates"

Code Review Checklist

Before submitting changes, ensure:

• Code follows TypeScript and style conventions
• All linting errors are fixed
• Documentation is updated (if needed)
• Security considerations are addressed
• Changes are tested locally
• Commit messages are clear and descriptive

Testing

Manual Testing

• Test all user flows:

  • User login and authentication
  • Photo upload and email notifications
  • Guess submission and point awarding
  • Admin user management
  • Password changes

• Test edge cases:

  • Invalid inputs
  • Unauthorized access attempts
  • Missing data
  • Network errors

Database Testing

• Test with fresh database migrations
• Verify seed script works correctly
• Test with various data states

Adding Tests (Future)

If tests are added to the project:

• Unit tests: Test utility functions and helpers
• Integration tests: Test API routes and database operations
• E2E tests: Test complete user flows
• Update test coverage when adding new features

Documentation Updates

When to Update Documentation

• README.md: When setup steps, features, or usage changes
• ARCHITECTURE.md: When system design, data flows, or patterns change
• CONTRIBUTING.md: When coding conventions or workflow changes
• SECURITY.md: When security practices or vulnerabilities change
• .cursor/rules: When project rules or guidelines change

Documentation Standards

• Keep docs up to date - outdated docs are worse than no docs
• Be clear and concise - use examples when helpful
• Cross-reference - link to related documentation
• Update all relevant docs - don't update just one file

Guidelines for AI Tools (Cursor)

If you're using AI tools like Cursor to help with development:

1. Respect these conventions:

   • Follow the coding style and patterns outlined here
   • Use the established folder structure
   • Maintain consistency with existing code

2. Prefer incremental changes:

   • Make small, focused changes rather than large refactors
   • Test each change before moving to the next
   • Keep commits focused and reviewable

3. Update documentation:

   • When AI generates code that changes behavior, update relevant docs
   • Keep architecture docs in sync with code changes
   • Document any new patterns or conventions

4. Security awareness:

   • Never generate code that exposes sensitive data
   • Always include authorization checks
   • Validate all user inputs
   • Follow security guidelines in SECURITY.md

5. Read before generating:

   • Always read relevant documentation first
   • Understand existing patterns before creating new code
   • Check similar features for consistency

Questions?

If you have questions about:

• Setup issues: Check README.md
• Architecture questions: Check ARCHITECTURE.md
• Security concerns: Check SECURITY.md
• Coding conventions: Check this file and .cursor/rules/mirrormatch.mdc

Important Reminders

• Always read documentation before making large changes
• Keep documentation updated when behavior changes
• Follow security guidelines strictly
• Test your changes before committing
• Write clear commit messages
• Maintain consistency with existing code

---

Last Updated: When conventions or workflow change, update this file and notify contributors.