Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
403 lines (283 loc) · 9.19 KB

CONTRIBUTING.md

File metadata and controls

403 lines (283 loc) · 9.19 KB
Raw

Contributing to RetroLoop

Thank you for your interest in contributing to RetroLoop! This document provides guidelines and workflows for contributing to this project.

Table of Contents

Getting Started

Prerequisites

  • Node.js 24+
  • Yarn 4.x (packageManager is set in package.json)
  • PostgreSQL 16+
  • Git

Initial Setup

  1. Fork the repository on GitHub

  2. Clone your fork:

    git clone https://github.com/runtimebug/retroloop.git
cd retroloop

  3. Install dependencies:

    yarn install

  4. Configure environment:

    cp .env.example .env
# Edit .env with your database credentials, JWT_SECRET, etc.

  5. Set up the database:

    # Start PostgreSQL (via Docker)
docker-compose up -d

  6. Run migrations and build shared types:

    yarn workspace @retro/shared-types build-lib
yarn workspace back db:migrate

  7. Start development servers:

    # Terminal 1: Backend
yarn dev:back

# Terminal 2: Frontend
yarn dev:front

Development Workflow

1. Create a Branch

Always create a new branch from main for your work:

git checkout main
git pull origin main
git checkout -b type/short-description

2. Make Your Changes

  • Write code following our style guidelines
  • Add or update tests as needed
  • Update documentation if applicable

3. Run Quality Checks

Before committing, ensure all checks pass:

# Lint and format
yarn lint
yarn format:check

# Type check
yarn workspace back build
yarn workspace front build

# Run tests
yarn workspace back test

4. Commit Your Changes

Follow our commit message conventions.

5. Push and Create Pull Request

git push -u origin type/short-description

Then open a Pull Request on GitHub.

Branch Naming Conventions

Use the following prefixes for branch names:

Prefix Purpose Example
feat/ New features or enhancements feat/dark-mode
fix/ Bug fixes fix/login-redirect
hotfix/ Urgent production fixes hotfix/security-patch
docs/ Documentation changes docs/api-examples
refactor/ Code refactoring refactor/auth-service
test/ Adding or updating tests test/auth-unit-tests
chore/ Maintenance tasks chore/update-deps

Commit Message Conventions

We follow Angular commit conventions Angular Conventional Commits:

Types

Type Description
feat A new feature
fix A bug fix
docs Documentation only changes
style Code style changes (formatting, missing semi colons, etc)
refactor Code change that neither fixes a bug nor adds a feature
perf Performance improvements
test Adding or correcting tests
chore Changes to build process or auxiliary tools

Examples

feat(front): add dark mode toggle

fix(back): resolve WebSocket reconnection issue
docs(back): update API endpoint documentation
refactor(front): extract card service from gateway
test(back): add unit tests for auth service

Guidelines

  • Use present tense ("add feature" not "added feature")
  • Use imperative mood ("move cursor to..." not "moves cursor to...")
  • Limit the first line to 72 characters or less
  • Reference issues and PRs in the footer when applicable

Code Style Guidelines

TypeScript

  • Strict mode enabled - All strict compiler options are on
  • Use explicit return types for public functions
  • Prefer interface over type for object shapes
  • Use unknown instead of any where possible

Formatting

We use ESLint and Prettier for automated formatting. Run yarn lint:fix before committing.

Import Order

Backend

// NestJS imports first
import { Injectable } from '@nestjs/common';

// Third-party imports
import { eq } from 'drizzle-orm';

// Shared types (workspace dependency)
import type { User } from '@retro/shared-types';

// Internal imports
import { usersTable } from '../database/schema';

Frontend

// React/Next imports first
import { memo, useCallback } from 'react';

// Third-party imports
import { motion } from 'framer-motion';
import { toast } from 'sonner';

// Direct icon imports (bundle size optimization)
import X from 'lucide-react/dist/esm/icons/x';
import Plus from 'lucide-react/dist/esm/icons/plus';

// Internal imports
import { apiClient } from '../lib/api-client';

Component Patterns

'use client';

import { memo, useCallback } from 'react';
import { motion } from 'framer-motion';

// Memoize components for performance
export const MyComponent = memo(function MyComponent({
	data,
	onAction,
}: MyComponentProps) {
	// Use functional setState
	const handleClick = useCallback(() => {
		onAction(data);
	}, [data, onAction]);

	return (
		<motion.div whileHover={{ scale: 1.02 }}>
			<button onClick={handleClick}>Action</button>
		</motion.div>
	);
});

File Naming

  • Use kebab-case for files: my-component.tsx
  • Use PascalCase for React components: MyComponent
  • Use camelCase for utilities and hooks: useLocalStorage.ts

Pull Request Process

Before Submitting

  1. Update your branch with the latest main:

    git fetch origin
git merge origin/main

  2. Run all checks:

    yarn lint
yarn format:check
yarn workspace back test
yarn workspace front test

  3. Fill out the PR template completely

PR Requirements

  • PR title should follow commit message conventions
  • Include a clear description of what changed and why
  • Link any related issues (e.g., "Fixes #123")
  • Add screenshots for UI changes
  • Ensure all CI checks pass

PR Size Guidelines

  • Small PRs (< 200 lines): Quick review, preferred
  • Medium PRs (200-500 lines): Acceptable with good description
  • Large PRs (> 500 lines): Consider breaking into smaller PRs

Testing

Backend Tests

# Run unit tests
yarn workspace back test

# Run with coverage
yarn workspace back test --coverage

# Run E2E tests
yarn workspace back test:e2e

Frontend Tests

# Run unit tests
yarn workspace front test

# Run with coverage
yarn workspace front test:coverage

Test Coverage Expectations

  • New features should include unit tests
  • Bug fixes should include a test that reproduces the bug
  • Aim for meaningful coverage, not just high percentages

Writing Tests

Backend Unit Test Pattern

describe('AuthService', () => {
	let service: AuthService;
	let mockUserRepository: jest.Mocked<UserRepository>;

	beforeEach(() => {
		mockUserRepository = createMock<UserRepository>();
		service = new AuthService(mockUserRepository);
	});

	describe('login', () => {
		it('should return token for valid credentials', async () => {
			// Arrange
			mockUserRepository.findByEmail.mockResolvedValue(mockUser);

			// Act
			const result = await service.login('test@example.com', 'password');

			// Assert
			expect(result.token).toBeDefined();
		});
	});
});

Review Expectations

For Authors

  • Respond to review comments within 48 hours
  • Resolve conversations after addressing feedback
  • Request re-review when ready
  • Be open to feedback and suggestions

For Reviewers

  • Review PRs within 2 business days
  • Focus on:
    • Correctness: Does it work as intended?
    • Security: Any potential vulnerabilities?
    • Performance: Any obvious bottlenecks?
    • Maintainability: Is the code readable and well-structured?
    • Tests: Are there adequate tests?
  • Use "Request changes" for blocking issues
  • Use "Comment" for suggestions
  • Use "Approve" when satisfied

Review Checklist

  • Code follows style guidelines
  • Tests are included and pass
  • No hardcoded secrets or credentials
  • Error handling is appropriate
  • Documentation is updated (if needed)
  • No console.log statements left in production code

Questions?

If you have questions or need help:

  1. Check existing issues and discussions
  2. Open a new issue with the question label
  3. Ask in your PR if it's specific to your changes

Thank you for contributing to RetroLoop!