Contributing to LifeQuest

First off, thank you for considering contributing to LifeQuest! 🎉

It's people like you that make LifeQuest such a great tool for gamifying productivity.

Code of Conduct
How Can I Contribute?
Development Setup
Pull Request Process
Coding Standards
Commit Message Guidelines

Code of Conduct

This project and everyone participating in it is governed by our Code of Conduct. By participating, you are expected to uphold this code.

Our Standards

✅ Be respectful and inclusive
✅ Welcome newcomers and help them get started
✅ Focus on what is best for the community
✅ Show empathy towards other community members
❌ No harassment, trolling, or discriminatory behavior
❌ No spam or self-promotion

How Can I Contribute?

Reporting Bugs

Before creating bug reports, please check existing issues to avoid duplicates.

When creating a bug report, include:

Clear title and description
Steps to reproduce the issue
Expected behavior vs actual behavior
Screenshots if applicable
Environment details (OS, browser, Node version, etc.)

Bug Report Template:

**Describe the bug**
A clear description of what the bug is.

**To Reproduce**
Steps to reproduce the behavior:
1. Go to '...'
2. Click on '...'
3. See error

**Expected behavior**
What you expected to happen.

**Screenshots**
If applicable, add screenshots.

**Environment:**
 - OS: [e.g. macOS 14.0]
 - Browser: [e.g. Chrome 120]
 - Node Version: [e.g. 18.17.0]

Suggesting Features

Feature suggestions are welcome! Please:

Check if the feature has already been suggested
Provide a clear use case
Explain how it benefits users
Consider implementation complexity

Feature Request Template:

**Is your feature request related to a problem?**
A clear description of the problem.

**Describe the solution you'd like**
A clear description of what you want to happen.

**Describe alternatives you've considered**
Any alternative solutions or features you've considered.

**Additional context**
Add any other context or screenshots.

Contributing Code

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Make your changes
Write/update tests
Ensure all tests pass
Commit your changes (see commit guidelines below)
Push to your fork (git push origin feature/amazing-feature)
Open a Pull Request

Development Setup

Prerequisites

Node.js 18+ and npm/yarn
PostgreSQL 14+ (or Docker)
Git

Initial Setup

# 1. Fork and clone the repository
git clone https://github.com/YOUR_USERNAME/lifequest.git
cd lifequest

# 2. Install dependencies
npm install

# 3. Set up environment variables
cp .env.example .env
# Edit .env with your local configuration

# 4. Set up the database
npm run db:setup

# 5. Run migrations
npm run db:migrate

# 6. Seed the database (optional)
npm run db:seed

# 7. Start development servers
npm run dev

Project Structure

lifequest/
├── frontend/          # Next.js web app
├── backend/           # Node.js API server
├── mobile/            # React Native app
├── shared/            # Shared types and utilities
└── docs/              # Documentation

Running Tests

# Run all tests
npm test

# Run tests in watch mode
npm run test:watch

# Run tests with coverage
npm run test:coverage

# Run specific test file
npm test -- path/to/test.spec.ts

Running Linters

# Lint all code
npm run lint

# Fix auto-fixable issues
npm run lint:fix

# Format code with Prettier
npm run format

Pull Request Process

Before Submitting

Code follows the project's style guidelines
All tests pass (npm test)
No linting errors (npm run lint)
Documentation is updated if needed
Commit messages follow our guidelines
Branch is up to date with main

PR Title Format

Use conventional commit format:

type(scope): brief description

Examples:
feat(tasks): add recurring task support
fix(auth): resolve token refresh issue
docs(api): update authentication endpoints

PR Description Template

## Description
Brief description of changes

## Type of Change
- [ ] Bug fix (non-breaking change which fixes an issue)
- [ ] New feature (non-breaking change which adds functionality)
- [ ] Breaking change (fix or feature that would cause existing functionality to not work as expected)
- [ ] Documentation update

## How Has This Been Tested?
Describe the tests you ran

## Checklist
- [ ] My code follows the style guidelines
- [ ] I have performed a self-review
- [ ] I have commented my code where necessary
- [ ] I have updated the documentation
- [ ] My changes generate no new warnings
- [ ] I have added tests that prove my fix/feature works
- [ ] New and existing tests pass locally

Review Process

Automated Checks: CI/CD runs tests and linting
Code Review: At least one maintainer reviews the code
Feedback: Address any requested changes
Approval: Once approved, a maintainer will merge

Coding Standards

TypeScript

// ✅ Good
interface User {
  id: string;
  name: string;
  email: string;
}

const getUser = async (id: string): Promise<User> => {
  // Implementation
};

// ❌ Bad
const getUser = async (id) => {
  // Missing types
};

React Components

// ✅ Good - Functional component with TypeScript
interface TaskCardProps {
  task: Task;
  onComplete: (id: string) => void;
}

export const TaskCard: React.FC<TaskCardProps> = ({ task, onComplete }) => {
  return (
    <div className="task-card">
      <h3>{task.title}</h3>
      <button onClick={() => onComplete(task.id)}>Complete</button>
    </div>
  );
};

// ❌ Bad - Missing types
export const TaskCard = ({ task, onComplete }) => {
  // Implementation
};

File Naming

Components: PascalCase (TaskCard.tsx)
Utilities: camelCase (formatDate.ts)
Constants: UPPER_SNAKE_CASE (API_ENDPOINTS.ts)
Types: PascalCase (User.ts, types.ts)

Code Organization

// ✅ Good - Organized imports
import React, { useState, useEffect } from 'react';
import { useRouter } from 'next/navigation';

import { Button } from '@/components/ui/button';
import { TaskCard } from '@/components/TaskCard';

import { useAuth } from '@/hooks/useAuth';
import { formatDate } from '@/lib/utils';

import type { Task } from '@/types';

// ❌ Bad - Unorganized imports
import { formatDate } from '@/lib/utils';
import React from 'react';
import { TaskCard } from '@/components/TaskCard';
import type { Task } from '@/types';

Error Handling

// ✅ Good - Proper error handling
try {
  const result = await apiCall();
  return result;
} catch (error) {
  if (error instanceof APIError) {
    logger.error('API call failed', { error });
    throw new UserFacingError('Failed to fetch data');
  }
  throw error;
}

// ❌ Bad - Silent failures
try {
  const result = await apiCall();
  return result;
} catch (error) {
  // Silent failure
}

Commit Message Guidelines

We follow Conventional Commits.

Format

type(scope): subject

body (optional)

footer (optional)

Types

feat: New feature
fix: Bug fix
docs: Documentation changes
style: Code style changes (formatting, etc.)
refactor: Code refactoring
perf: Performance improvements
test: Adding or updating tests
chore: Maintenance tasks
ci: CI/CD changes

Examples

# Feature
git commit -m "feat(tasks): add recurring task support"

# Bug fix
git commit -m "fix(auth): resolve token refresh issue"

# Documentation
git commit -m "docs(api): update authentication endpoints"

# With body
git commit -m "feat(gamification): add streak bonuses

Implements streak bonus multipliers that increase XP
rewards for consecutive days of task completion.

Closes #123"

Scope

Common scopes:

tasks
goals
auth
api
ui
mobile
gamification
rewards

Testing Guidelines

Unit Tests

// Example: Testing a utility function
describe('calculateXP', () => {
  it('should calculate base XP correctly', () => {
    const task = { xp_value: 50, difficulty: 'medium' };
    expect(calculateXP(task)).toBe(50);
  });

  it('should apply streak bonus', () => {
    const task = { xp_value: 50, difficulty: 'medium' };
    const streak = 7;
    expect(calculateXP(task, streak)).toBe(75);
  });
});

Integration Tests

// Example: Testing an API endpoint
describe('POST /api/tasks/:id/complete', () => {
  it('should complete task and award XP', async () => {
    const response = await request(app)
      .post('/api/tasks/123/complete')
      .set('Authorization', `Bearer ${token}`)
      .expect(200);

    expect(response.body.xp_gained).toBeGreaterThan(0);
    expect(response.body.task.status).toBe('completed');
  });
});

Documentation

Code Comments

// ✅ Good - Explains why, not what
// Use exponential backoff to avoid overwhelming the API
const retryWithBackoff = async (fn: Function, retries = 3) => {
  // Implementation
};

// ❌ Bad - States the obvious
// This function retries
const retryWithBackoff = async (fn: Function, retries = 3) => {
  // Implementation
};

JSDoc for Public APIs

/**
 * Calculates XP earned for completing a task
 * @param task - The completed task
 * @param streak - Current streak days (optional)
 * @returns Total XP earned including bonuses
 */
export const calculateXP = (task: Task, streak?: number): number => {
  // Implementation
};

Getting Help

💬 Discord: Join our community
📧 Email: dev@lifequest.app
📖 Docs: Full documentation
🐛 Issues: GitHub Issues

Recognition

Contributors will be:

Listed in our CONTRIBUTORS.md file
Mentioned in release notes for significant contributions
Eligible for special badges in the app (coming soon!)

Thank you for contributing to LifeQuest! 🚀

Every contribution, no matter how small, helps make productivity more engaging for everyone.

FilesExpand file tree

CONTRIBUTING.md

Latest commit

History