feat: add CONTRIBUTING.md and LICENSE files for project guidelines and legal terms
This commit is contained in:
Thibault Pouch
318
CONTRIBUTING.md
Normal file
318
CONTRIBUTING.md
Normal file
@@ -0,0 +1,318 @@
|
||||
# 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 `.env` files based on the examples in each project. 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!
|
||||
Reference in New Issue
Block a user