# Contributing to CrowMate Nest

Thank you for your interest in contributing to the Nest platform for Headless Hazard! This document provides guidelines and workflows for contributing to this monorepo.

## Table of Contents

- [Code of Conduct](#code-of-conduct)
- [Getting Started](#getting-started)
- [Development Workflow](#development-workflow)
- [Coding Standards](#coding-standards)
- [Testing Guidelines](#testing-guidelines)
- [Commit Messages](#commit-messages)
- [Pull Request Process](#pull-request-process)
- [Project Structure](#project-structure)

## Code of Conduct

- Be respectful and constructive in all communications
- Focus on what is best for the community and the project
- Show empathy towards other contributors
- Accept constructive criticism gracefully

## Getting Started

### 1. Fork and Clone (External Contributors)

```bash
git clone https://github.com/CrowMate/Nest.git
cd Nest
```

### 2. Install Dependencies

Install dependencies for each sub-project you'll be working on:

```bash
# Backend
cd nest-backend
npm install

# Public Frontend
cd ../nest-front
npm install

# Internal Portal
cd ../nest-intra
npm install
```

### 3. Set Up Environment

Create a root `.env` file from `.env.example` (`cp .env.example .env`) and adjust values as needed. See the main [README.md](./README.md) for required environment variables.

### 4. Create a Branch

Always create a new branch from `main` for your work:

```bash
git checkout main
git pull origin main
git checkout -b feature/your-feature-name
```

Branch naming conventions:
- `feature/` - New features
- `fix/` - Bug fixes
- `refactor/` - Code refactoring
- `docs/` - Documentation updates
- `style/` - Code style changes (formatting, etc.)
- `test/` - Adding or updating tests

## Development Workflow

### Running Development Servers

```bash
# Backend (port 3000)
cd nest-backend
npm run dev

# Frontend (port 5173)
cd nest-front
npm run dev

# Intranet (port 5174)
cd nest-intra
npm run dev
```

### Database Changes (Backend)

When modifying the Prisma schema:

```bash
cd nest-backend

# Push changes directly (development)
npm run db:push

# Or create a migration (production-ready)
npm run db:migrate

# Re-seed if needed
npm run db:seed
```

## Coding Standards

### TypeScript

- **Use TypeScript strictly** - avoid `any` types
- **Define interfaces/types** for all data structures
- **Export types** from centralized locations (e.g., `src/types/index.ts`)
- **Use named exports** over default exports where possible

### Code Style

- **2 spaces** for indentation
- **Single quotes** for strings
- **Semicolons** required
- **Trailing commas** in multi-line objects/arrays
- **No unused imports** or variables

### Linting

Run linters before committing:

```bash
# Frontend projects
npm run lint

# Backend - ensure TypeScript compiles without errors
npm run build
```

### Naming Conventions

- **Variables/Functions**: `camelCase`
- **Components**: `PascalCase`
- **Files**: Match the exported component/function name
- **Constants**: `UPPER_SNAKE_CASE`
- **Database fields**: `camelCase` (Prisma convention)

### File Organization

```
src/
├── components/        # React components
│   ├── layout/       # Layout components (headers, sidebars)
│   └── shared/       # Reusable components
├── contexts/         # React contexts
├── pages/            # Route pages
├── types/            # TypeScript type definitions
├── utils/            # Utility functions
└── data/             # Mock data, constants
```

## Testing Guidelines

### Backend Testing

- Test all API endpoints with valid and invalid data
- Verify authentication and authorization
- Test database operations and constraints
- Use tools like Postman or Thunder Client

### Frontend Testing

- Test user flows manually in the browser
- Verify responsive design at different breakpoints
- Test authentication flows (login, logout, protected routes)
- Ensure error states are handled gracefully

### Manual Testing Checklist

Before submitting a PR:

- [ ] Code runs without errors
- [ ] New features work as intended
- [ ] Existing features still work (no regressions)
- [ ] UI is responsive and accessible
- [ ] Forms validate properly
- [ ] Error messages are clear and helpful
- [ ] Console has no warnings or errors

## Commit Messages

Follow conventional commit format:

```
<type>(<scope>): <subject>

<body>

<footer>
```

### Types

- `feat` - New feature
- `fix` - Bug fix
- `docs` - Documentation changes
- `style` - Code style changes (formatting, semicolons, etc.)
- `refactor` - Code refactoring without feature changes
- `perf` - Performance improvements
- `test` - Adding or updating tests
- `chore` - Build process, dependency updates, etc.

### Examples

```
feat(forum): add reply editing functionality

Users can now edit their forum replies within 24 hours of posting.
Includes validation and authorization checks.

Closes #42
```

```
fix(auth): resolve JWT expiration handling

Fixed issue where expired tokens weren't properly refreshed,
causing users to be logged out unexpectedly.
```

```
docs(readme): update Docker deployment instructions
```

## Pull Request Process

### 1. Before Submitting

- [ ] Code follows style guidelines
- [ ] All linting passes
- [ ] TypeScript compiles without errors
- [ ] Manual testing completed
- [ ] No console errors or warnings
- [ ] Commits follow commit message format

### 2. Create Pull Request

1. Push your branch to the repository
2. Open a Pull Request against `main`
3. Fill out the PR template with:
   - **Description**: What does this PR do?
   - **Changes**: List of main changes
   - **Testing**: How was this tested?
   - **Screenshots**: (if UI changes)
   - **Related Issues**: Link any related issues

### 3. PR Title Format

Use the same format as commit messages:

```
feat(backend): add team member endpoints
fix(frontend): resolve login form validation issue
```

### 4. Review Process

- At least one team member must review and approve
- Address all review comments
- Keep the PR focused - one feature/fix per PR
- Rebase if needed to resolve conflicts

### 5. Merging

- Squash and merge is preferred for clean history
- Delete the branch after merging
- Ensure CI/CD passes (if configured)

## Project Structure

### Backend (`nest-backend/`)

```
src/
├── app.ts              # Express app configuration
├── index.ts            # Server entry point
├── lib/
│   └── prisma.ts      # Prisma client instance
├── middleware/
│   └── auth.ts        # JWT authentication middleware
└── routes/            # API route handlers
    ├── auth.ts
    ├── bugs.ts
    ├── events.ts
    ├── feed.ts
    ├── forum.ts
    ├── team.ts
    └── users.ts
```

### Frontend (`nest-front/` and `nest-intra/`)

```
src/
├── components/        # Reusable React components
├── contexts/         # Global state (Auth, etc.)
├── pages/            # Route page components
├── types/            # TypeScript definitions
├── utils/            # Helper functions
└── data/             # Constants and mock data
```

## Questions or Issues?

- Check existing issues before creating new ones
- Use GitHub Discussions for questions
- Tag relevant team members for guidance
- Reference issue numbers in commits and PRs

---

Thank you for contributing to CrowMate Nest!