tududi/.github/CONTRIBUTING.md

Contributing to tududi

Thank you for your interest in contributing to tududi! This guide will help you get started.

Table of Contents

• Code of Conduct
• Getting Started
• Development Workflow
• Code Standards
• Testing
• Database Changes
• Translations
• Pull Request Process

Code of Conduct

Please be respectful and constructive in all interactions. We want to foster an inclusive and welcoming community.

Getting Started

Prerequisites

• Node.js (v22 or higher recommended)
• npm
• Git

Setup

1. Fork and clone the repository

   git clone https://github.com/chrisvel/tududi.git
   cd tududi
   

2. Install dependencies

   npm install
   

3. Initialize the database

   npm run db:init
   

4. Start the development server

   npm start
   

   This starts both frontend (http://localhost:8080) and backend (http://localhost:5000)

5. Create a test user (optional)

   npm run user:create
   

Development Workflow

Branch Naming

• feature/description - New features
• fix/description - Bug fixes
• refactor/description - Code refactoring
• docs/description - Documentation changes
• test/description - Test additions or fixes

Before You Start

1. Check existing issues and discussions to avoid duplicate work
2. Create or comment on an issue describing what you plan to work on
3. Create a new branch from main

   git checkout -b feature/your-feature-name
   

Development Commands

# Start development server (frontend + backend)
npm start

# Run frontend only
npm run frontend:dev

# Run backend only
npm run backend:dev

# Run tests
npm test                    # Backend tests
npm run test:ui            # E2E tests
npm run test:coverage      # Coverage report

# Linting and formatting
npm run lint               # Check all code
npm run lint:fix           # Auto-fix linting issues
npm run format:fix         # Auto-format code

# Database commands
npm run db:migrate         # Run migrations
npm run db:seed            # Seed dev data
npm run db:reset           # Reset database

Code Standards

General Rules

• TypeScript for all new code
• ESLint and Prettier are configured - run before committing:

  npm run lint:fix && npm run format:fix
  

• Follow existing code style and patterns
• Write meaningful variable and function names
• Add comments for complex logic

Frontend (React + TypeScript)

• Use functional components with hooks
• Keep components small and focused
• Use TypeScript interfaces for props
• Place new components in frontend/components/
• Follow existing folder structure

Backend (Node.js + Express)

• Use async/await (no callbacks)
• Validate input using middleware
• Use Sequelize models for database access
• Follow RESTful API conventions
• Place routes in backend/routes/
• Place business logic in backend/services/

Security

• Never commit secrets, API keys, or credentials
• Validate and sanitize all user input
• Use parameterized queries (Sequelize handles this)
• Follow OWASP best practices

Testing

Requirements

• Bug fixes must include a test that would have caught the bug
• New features should include relevant tests
• All tests must pass before submitting PR

Running Tests

# Backend unit tests
npm run backend:test

# Frontend tests
npm run frontend:test

# E2E tests
npm run test:ui

# Watch mode (useful during development)
npm run test:watch

Writing Tests

• Place backend tests in backend/tests/
• Place frontend tests alongside components as *.test.tsx
• Use descriptive test names
• Follow the Arrange-Act-Assert pattern

Database Changes

Creating Migrations

If your changes require database schema changes:

1. Create a migration

   npm run migration:create -- --name your-migration-name
   

2. Edit the migration file in backend/migrations/

3. Test the migration

   npm run migration:run      # Apply
   npm run migration:undo     # Rollback to test
   

4. Update Sequelize models in backend/models/

5. Include migrations in your PR

Migration Best Practices

• Make migrations reversible (implement down method)
• Test both up and down migrations
• Don't modify existing migrations that have been released
• Use transactions for data migrations

Translations

tududi supports multiple languages via i18next.

Adding/Updating Translations

1. Add keys to English (source of truth): frontend/locales/en/translation.json

2. Sync translations

   npm run translations:sync
   

3. Check for missing translations

   npm run translations:check
   

Translation Guidelines

• Use descriptive key names: task.create.button not btn1
• Keep translations concise for UI elements
• Don't translate in code - always use translation keys
• Include context in comments if meaning is ambiguous

Pull Request Process

Before Submitting

1. Update your branch with latest main

   git checkout main
   git pull origin main
   git checkout your-branch
   git rebase main
   

2. Run the pre-push checks

   npm run pre-push
   

   This runs linting, formatting, and tests.

3. Test your changes thoroughly

   • Manual testing in the browser
   • Run automated tests
   • Test on different screen sizes (mobile/desktop)

Creating the PR

1. Push your branch

   git push origin your-branch
   

2. Create Pull Request on GitHub

3. Fill out the PR template with:

   • Clear description of changes
   • Related issue numbers (use Fixes #123)
   • Testing steps
   • Screenshots (if UI changes)

4. Wait for review - maintainers will review and may request changes

PR Requirements

• ✅ All tests passing
• ✅ Code follows style guidelines
• ✅ No linting errors
• ✅ Meaningful commit messages
• ✅ Documentation updated (if needed)
• ✅ Migrations included (if database changes)

Questions?

• General questions: Use GitHub Discussions
• Bug reports: Create an issue
• Feature requests: Start a discussion

---

Thank you for contributing to tududi! 🎉