Contributing to TaskOrbit

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

Code of Conduct
How Can I Contribute?
Development Setup
Pull Request Process
Coding Standards
Commit Messages
Project Structure

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. Please report unacceptable behavior to pasindulankaa@gmail.com.

Our Standards

Using welcoming and inclusive language
Being respectful of differing viewpoints and experiences
Gracefully accepting constructive criticism
Focusing on what is best for the community
Showing empathy towards other community members

How Can I Contribute?

Reporting Bugs

Before creating bug reports, please check the existing issues to avoid duplicates. When you create a bug report, include as many details as possible:

Use a clear and descriptive title
Describe the exact steps to reproduce the problem
Provide specific examples
Describe the behavior you observed and what you expected
Include screenshots if possible
Include your environment details (OS, Node version, browser, etc.)

Suggesting Enhancements

Enhancement suggestions are tracked as GitHub issues. When creating an enhancement suggestion, include:

Use a clear and descriptive title
Provide a detailed description of the suggested enhancement
Explain why this enhancement would be useful
List any alternative solutions you've considered

Your First Code Contribution

Unsure where to begin? You can start by looking through these issues:

good-first-issue - Issues that should only require a few lines of code
help-wanted - Issues that are a bit more involved
documentation - Improvements to documentation

Development Setup

Prerequisites

Node.js 18+ or 20+
pnpm 9.0.0+
MongoDB (local or Atlas)
Git

Setup Steps

Fork and clone the repository

git clone https://github.com/YOUR-USERNAME/task-orbit.git
cd task-orbit

Add upstream remote

git remote add upstream https://github.com/ORIGINAL-OWNER/task-orbit.git

Install dependencies

pnpm install

Set up environment variables

Copy the example env files and fill in your values:

# API
cp apps/api/.env.example apps/api/.env

# Web
cp apps/web/.env.example apps/web/.env

Start MongoDB

# macOS
brew services start mongodb-community

# Or manually
mongod --dbpath /path/to/data

Seed the database (optional)

cd apps/api
pnpm seed

Start development servers

# From root directory
pnpm dev

Pull Request Process

Before Submitting

Create a new branch from dev (not main)

git checkout dev
git pull upstream dev
git checkout -b feature/your-feature-name

Make your changes

Write clear, concise code
Follow the coding standards
Add tests if applicable
Update documentation as needed

Test your changes

# Type checking
pnpm check-types

# Linting
pnpm lint

# Format code
pnpm format

# Build
pnpm build

Commit your changes

git add .
git commit -m "feat: add amazing feature"

Submitting the PR

Push to your fork

git push origin feature/your-feature-name

Create Pull Request

Go to the original repository on GitHub
Click "New Pull Request"
Select your fork and branch
Fill in the PR template with details

PR Requirements

Code follows the project's coding standards
Tests pass (if applicable)
Documentation updated (if needed)
Commit messages follow conventions
No merge conflicts
Reviewed by at least one maintainer

After Submission

Be responsive to feedback
Make requested changes promptly
Keep your PR up to date with the base branch

# Sync with upstream
git fetch upstream
git rebase upstream/dev
git push origin feature/your-feature-name --force

Coding Standards

TypeScript

Use TypeScript for all new code
Define proper types - avoid any unless absolutely necessary
Use interfaces for object shapes
Export types that are used in multiple files

// Good
interface Task {
  id: string;
  title: string;
  status: TaskStatus;
}

// Avoid
const task: any = { ... };

React Components

Use functional components with hooks
Use TypeScript for props
Keep components small and focused
Extract reusable logic into custom hooks

// Good
interface TaskCardProps {
  task: Task;
  onUpdate: (task: Task) => void;
}

export const TaskCard: React.FC<TaskCardProps> = ({ task, onUpdate }) => {
  // Component logic
};

File Naming

Components: PascalCase (e.g., TaskCard.tsx)
Hooks: camelCase with use prefix (e.g., useTaskManager.ts)
Utilities: camelCase (e.g., formatDate.ts)
Types: PascalCase (e.g., Task.ts)
Constants: UPPER_SNAKE_CASE (e.g., API_ENDPOINTS.ts)

Code Organization

// 1. Imports (external first, then internal)
import React from 'react';
import { useQuery } from '@tanstack/react-query';

import { Task } from '@/types/task';
import { useAuth } from '@/hooks/useAuth';

// 2. Types/Interfaces
interface ComponentProps {
  // ...
}

// 3. Constants
const DEFAULT_STATUS = 'todo';

// 4. Component
export const Component: React.FC<ComponentProps> = (props) => {
  // 4a. Hooks
  const { user } = useAuth();

  // 4b. State
  const [state, setState] = useState();

  // 4c. Effects
  useEffect(() => {
    // ...
  }, []);

  // 4d. Handlers
  const handleClick = () => {
    // ...
  };

  // 4e. Render
  return (
    // JSX
  );
};

Styling

Use Tailwind CSS for styling
Follow the design system defined in apps/docs/ui-revamp-*.md
Use Shadcn components when available
Keep styles consistent with existing components

// Good - Using Tailwind classes
<div className="flex items-center gap-2 rounded-lg bg-background p-4">
  <span className="text-sm font-medium">Task</span>
</div>

API Endpoints

Use RESTful conventions
Validate input with express-validator
Handle errors properly
Return consistent responses

// Good
router.post('/tasks', authenticate, validateTask, async (req: Request, res: Response) => {
  try {
    const task = await Task.create(req.body);
    res.status(201).json({ success: true, data: task });
  } catch (error) {
    res.status(500).json({ success: false, error: error.message });
  }
});

Commit Messages

We follow the Conventional Commits specification.

Format

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

<body>

<footer>

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(board): add drag-and-drop for tasks"

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

# Documentation
git commit -m "docs: update README with deployment instructions"

# Refactor
git commit -m "refactor(api): simplify task controller logic"

# Multiple changes
git commit -m "feat(board): add kanban view

- Implement drag-and-drop with dnd-kit
- Add column management
- Update board types

Closes #123"

Project Structure

Monorepo Organization

task-orbit/
├── apps/
│   ├── api/          # Backend API
│   ├── web/          # Frontend app
│   └── docs/         # Documentation
├── packages/         # Shared packages
│   ├── eslint-config/
│   ├── typescript-config/
│   └── ui/
└── ...

Adding New Features

Frontend Component

Create component in apps/web/src/components/
Add types in apps/web/src/types/
Create service in apps/web/src/services/ if needed
Add to appropriate page in apps/web/src/pages/

Backend Endpoint

Create model in apps/api/src/models/
Add controller in apps/api/src/controllers/
Define routes in apps/api/src/routes/
Add middleware if needed in apps/api/src/middleware/

Testing

Running Tests

# Type checking
pnpm check-types

# Linting
pnpm lint

# Build test
pnpm build

Writing Tests

Add tests for new features
Update tests for modified features
Ensure tests pass before submitting PR

Documentation

When to Update Documentation

Adding new features
Changing existing functionality
Modifying API endpoints
Updating environment variables
Changing project structure

Documentation Files

README.md - Main project documentation
apps/api/src/scripts/README.md - Seed data documentation
apps/docs/*.md - Detailed specifications
Code comments - For complex logic

Questions?

If you have questions about contributing:

Check existing documentation
Search closed issues
Open a new issue with the question label
Contact maintainers via email

Recognition

Contributors will be recognized in:

GitHub contributors page
Release notes
Project documentation

Thank you for contributing to TaskOrbit! 🚀

FilesExpand file tree

CONTRIBUTING.md

Latest commit

History