diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..68b02db --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,408 @@ +# Contributing to Mosaic Stack + +Thank you for your interest in contributing to Mosaic Stack! This document provides guidelines and processes for contributing effectively. + +## Table of Contents + +- [Development Environment Setup](#development-environment-setup) +- [Code Style Guidelines](#code-style-guidelines) +- [Branch Naming Conventions](#branch-naming-conventions) +- [Commit Message Format](#commit-message-format) +- [Pull Request Process](#pull-request-process) +- [Testing Requirements](#testing-requirements) +- [Where to Ask Questions](#where-to-ask-questions) + +## Development Environment Setup + +### Prerequisites + +- **Node.js:** 20.0.0 or higher +- **pnpm:** 10.19.0 or higher (package manager) +- **Docker:** 20.10+ and Docker Compose 2.x+ (for database services) +- **Git:** 2.30+ for version control + +### Installation Steps + +1. **Clone the repository** + + ```bash + git clone https://git.mosaicstack.dev/mosaic/stack mosaic-stack + cd mosaic-stack + ``` + +2. **Install dependencies** + + ```bash + pnpm install + ``` + +3. **Set up environment variables** + + ```bash + cp .env.example .env + # Edit .env with your configuration + ``` + + Key variables to configure: + - `DATABASE_URL` - PostgreSQL connection string + - `OIDC_ISSUER` - Authentik OIDC issuer URL + - `OIDC_CLIENT_ID` - OAuth client ID + - `OIDC_CLIENT_SECRET` - OAuth client secret + - `JWT_SECRET` - Random secret for session tokens + +4. **Initialize the database** + + ```bash + # Start Docker services (PostgreSQL, Valkey) + docker compose up -d + + # Generate Prisma client + pnpm prisma:generate + + # Run migrations + pnpm prisma:migrate + + # Seed development data (optional) + pnpm prisma:seed + ``` + +5. **Start development servers** + + ```bash + pnpm dev + ``` + + This starts all services: + - Web: http://localhost:3000 + - API: http://localhost:3001 + +### Quick Reference Commands + +| Command | Description | +|---------|-------------| +| `pnpm dev` | Start all development servers | +| `pnpm dev:api` | Start API only | +| `pnpm dev:web` | Start Web only | +| `docker compose up -d` | Start Docker services | +| `docker compose logs -f` | View Docker logs | +| `pnpm prisma:studio` | Open Prisma Studio GUI | +| `make help` | View all available commands | + +## Code Style Guidelines + +Mosaic Stack follows strict code style guidelines to maintain consistency and quality. For comprehensive guidelines, see [CLAUDE.md](./CLAUDE.md). + +### Formatting + +We use **Prettier** for consistent code formatting: + +- **Semicolons:** Required +- **Quotes:** Double quotes (`"`) +- **Indentation:** 2 spaces +- **Trailing commas:** ES5 compatible +- **Line width:** 100 characters +- **End of line:** LF (Unix style) + +Run the formatter: +```bash +pnpm format # Format all files +pnpm format:check # Check formatting without changes +``` + +### Linting + +We use **ESLint** for code quality checks: + +```bash +pnpm lint # Run linter +pnpm lint:fix # Auto-fix linting issues +``` + +### TypeScript + +All code must be **strictly typed** TypeScript: +- No `any` types allowed +- Explicit type annotations for function returns +- Interfaces over type aliases for object shapes +- Use shared types from `@mosaic/shared` package + +### PDA-Friendly Design (NON-NEGOTIABLE) + +**Never** use demanding or stressful language in UI text: + +| ❌ AVOID | ✅ INSTEAD | +|---------|------------| +| OVERDUE | Target passed | +| URGENT | Approaching target | +| MUST DO | Scheduled for | +| CRITICAL | High priority | +| YOU NEED TO | Consider / Option to | +| REQUIRED | Recommended | + +See [docs/3-architecture/3-design-principles/1-pda-friendly.md](./docs/3-architecture/3-design-principles/1-pda-friendly.md) for complete design principles. + +## Branch Naming Conventions + +We follow a Git-based workflow with the following branch types: + +### Branch Types + +| Prefix | Purpose | Example | +|--------|---------|---------| +| `feature/` | New features | `feature/42-user-dashboard` | +| `fix/` | Bug fixes | `fix/123-auth-redirect` | +| `docs/` | Documentation | `docs/contributing` | +| `refactor/` | Code refactoring | `refactor/prisma-queries` | +| `test/` | Test-only changes | `test/coverage-improvements` | + +### Workflow + +1. Always branch from `develop` +2. Merge back to `develop` via pull request +3. `main` is for stable releases only + +```bash +# Start a new feature +git checkout develop +git pull --rebase +git checkout -b feature/my-feature-name + +# Make your changes +# ... + +# Commit and push +git push origin feature/my-feature-name +``` + +## Commit Message Format + +We use **Conventional Commits** for clear, structured commit messages: + +### Format + +``` +(#issue): Brief description + +Detailed explanation (optional). + +References: #123 +``` + +### Types + +| Type | Description | +|------|-------------| +| `feat` | New feature | +| `fix` | Bug fix | +| `docs` | Documentation changes | +| `test` | Adding or updating tests | +| `refactor` | Code refactoring (no functional change) | +| `chore` | Maintenance tasks, dependencies | + +### Examples + +```bash +feat(#42): add user dashboard widget + +Implements the dashboard widget with task and event summary cards. +Responsive design with PDA-friendly language. + +fix(#123): resolve auth redirect loop + +Fixed OIDC token refresh causing redirect loops on session expiry. +refactor(#45): extract database query utilities + +Moved duplicate query logic to shared utilities package. +test(#67): add coverage for activity service + +Added unit tests for all activity service methods. +docs: update API documentation for endpoints + +Clarified pagination and filtering parameters. +``` + +### Commit Guidelines + +- Keep the subject line under 72 characters +- Use imperative mood ("add" not "added" or "adds") +- Reference issue numbers when applicable +- Group related commits before creating PR + +## Pull Request Process + +### Before Creating a PR + +1. **Ensure tests pass** + ```bash + pnpm test + pnpm build + ``` + +2. **Check code coverage** (minimum 85%) + ```bash + pnpm test:coverage + ``` + +3. **Format and lint** + ```bash + pnpm format + pnpm lint + ``` + +4. **Update documentation** if needed + - API docs in `docs/4-api/` + - Architecture docs in `docs/3-architecture/` + +### Creating a Pull Request + +1. Push your branch to the remote + ```bash + git push origin feature/my-feature + ``` + +2. Create a PR via GitLab at: + https://git.mosaicstack.dev/mosaic/stack/-/merge_requests + +3. Target branch: `develop` + +4. Fill in the PR template: + - **Title:** `feat(#issue): Brief description` (follows commit format) + - **Description:** Summary of changes, testing done, and any breaking changes + +5. Link related issues using `Closes #123` or `References #123` + +### PR Review Process + +- **Automated checks:** CI runs tests, linting, and coverage +- **Code review:** At least one maintainer approval required +- **Feedback cycle:** Address review comments and push updates +- **Merge:** Maintainers merge after approval and checks pass + +### Merge Guidelines + +- **Rebase commits** before merging (keep history clean) +- **Squash** small fix commits into the main feature commit +- **Delete feature branch** after merge +- **Update milestone** if applicable + +## Testing Requirements + +### Test-Driven Development (TDD) + +**All new code must follow TDD principles.** This is non-negotiable. + +#### TDD Workflow: Red-Green-Refactor + +1. **RED** - Write a failing test first + ```bash + # Write test for new functionality + pnpm test:watch # Watch it fail + git add feature.test.ts + git commit -m "test(#42): add test for getUserById" + ``` + +2. **GREEN** - Write minimal code to pass the test + ```bash + # Implement just enough to pass + pnpm test:watch # Watch it pass + git add feature.ts + git commit -m "feat(#42): implement getUserById" + ``` + +3. **REFACTOR** - Clean up while keeping tests green + ```bash + # Improve code quality + pnpm test:watch # Ensure still passing + git add feature.ts + git commit -m "refactor(#42): extract user mapping logic" + ``` + +### Coverage Requirements + +- **Minimum 85% code coverage** for all new code +- **Write tests BEFORE implementation** — no exceptions +- Test files co-located with source: + - `feature.service.ts` → `feature.service.spec.ts` + - `component.tsx` → `component.test.tsx` + +### Test Types + +| Type | Purpose | Tool | +|------|---------|------| +| **Unit tests** | Test functions/methods in isolation | Vitest | +| **Integration tests** | Test module interactions (service + DB) | Vitest | +| **E2E tests** | Test complete user workflows | Playwright | + +### Running Tests + +```bash +pnpm test # Run all tests +pnpm test:watch # Watch mode for TDD +pnpm test:coverage # Generate coverage report +pnpm test:api # API tests only +pnpm test:web # Web tests only +pnpm test:e2e # Playwright E2E tests +``` + +### Coverage Verification + +After implementation: +```bash +pnpm test:coverage +# Open coverage/index.html in browser +# Verify your files show ≥85% coverage +``` + +### Test Guidelines + +- **Descriptive names:** `it("should return user when valid token provided")` +- **Group related tests:** Use `describe()` blocks +- **Mock external dependencies:** Database, APIs, file system +- **Avoid implementation details:** Test behavior, not internals + +## Where to Ask Questions + +### Issue Tracker + +All questions, bug reports, and feature requests go through the issue tracker: +https://git.mosaicstack.dev/mosaic/stack/issues + +### Issue Labels + +| Category | Labels | +|----------|--------| +| Priority | `p0` (critical), `p1` (high), `p2` (medium), `p3` (low) | +| Type | `api`, `web`, `database`, `auth`, `plugin`, `ai`, `devops`, `docs`, `testing` | +| Status | `todo`, `in-progress`, `review`, `blocked`, `done` | + +### Documentation + +Check existing documentation first: +- [README.md](./README.md) - Project overview +- [CLAUDE.md](./CLAUDE.md) - Comprehensive development guidelines +- [docs/](./docs/) - Full documentation suite + +### Getting Help + +1. **Search existing issues** - Your question may already be answered +2. **Create an issue** with: + - Clear title and description + - Steps to reproduce (for bugs) + - Expected vs actual behavior + - Environment details (Node version, OS, etc.) + +### Communication Channels + +- **Issues:** For bugs, features, and questions (primary channel) +- **Pull Requests:** For code review and collaboration +- **Documentation:** For clarifications and improvements + +--- + +**Thank you for contributing to Mosaic Stack!** Every contribution helps make this platform better for everyone. + +For more details, see: +- [Project README](./README.md) +- [Development Guidelines](./CLAUDE.md) +- [API Documentation](./docs/4-api/) +- [Architecture](./docs/3-architecture/)