Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
405 lines (298 loc) · 9.57 KB

CONTRIBUTING.md

File metadata and controls

405 lines (298 loc) · 9.57 KB

Contributing to Chronos

Thank you for your interest in contributing to Chronos! This document provides guidelines and instructions for contributing to the project.

English | 简体中文

📋 Table of Contents

📜 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.

  • Be respectful and inclusive
  • Focus on constructive feedback
  • Welcome newcomers and help them learn

🚀 Getting Started

  1. Fork the repository on GitHub
  2. Clone your fork locally: 
    git clone https://github.com/your-username/chronos.git
cd chronos
  3. Add upstream remote: 
    git remote add upstream https://github.com/original-owner/chronos.git
  4. Set up development environment (see Development Setup)

💡 How to Contribute

Types of Contributions

We welcome various types of contributions:

  • 🐛 Bug Fixes: Fix issues reported in GitHub Issues
  • ✨ New Features: Implement new functionality
  • 📝 Documentation: Improve docs, add examples, fix typos
  • 🎨 UI/UX Improvements: Enhance user interface and experience
  • ⚡ Performance Optimizations: Improve speed and efficiency
  • 🧪 Tests: Add or improve test coverage
  • 🔧 Refactoring: Improve code structure without changing behavior
  • 🌍 Translations: Help localize the application

Finding Issues to Work On

🛠️ Development Setup

Prerequisites

  • Node.js v18+ and npm
  • Python 3.12+
  • uv (Python package manager)
  • MySQL/SQLite/PostgreSQL

Backend Setup

cd Chronos-backend

# Install uv
pip install uv

# Install dependencies
uv sync

# Configure database
cp config/.secrets.toml.example config/.secrets.toml
# Edit config/.secrets.toml

# Seed database (optional)
uv run python -m src.scripts.seed

# Start server
uv run uvicorn src.main:app --reload

Frontend Setup

cd Chronos-frontend

# Install dependencies
npm install

# Start development server
npm start

📏 Coding Standards

General Guidelines

  • Write clean, readable, and maintainable code
  • Follow existing code style and conventions
  • Keep functions and components small and focused
  • Use meaningful variable and function names
  • Add comments for complex logic (not obvious code)

Backend (Python)

  • Follow PEP 8 style guide
  • Use type hints for function signatures
  • Write docstrings for public functions and classes
  • Format code with Black: 
    uv run black src/
  • Run linter: 
    uv run flake8 src/
  • Type checking: 
    uv run mypy src/

Frontend (TypeScript/Angular)

  • Follow Angular Style Guide
  • Use TypeScript strict mode
  • Use meaningful component selectors (prefix with app- or feature prefix)
  • Follow component best practices:
    • Smart components handle logic
    • Dumb components focus on presentation
  • Format code: 
    npx prettier --write "src/**/*.ts"
  • Lint code: 
    ng lint

File Naming Conventions

Backend:

  • Snake case for files: user_service.py
  • Pascal case for classes: UserService
  • Modules in folders: src/services/user_service.py

Frontend:

  • Kebab case for files: user-service.ts
  • Pascal case for classes/components: UserService, UserComponent
  • Feature suffix for components: user-list.component.ts

📝 Commit Guidelines

Commit Message Format

We follow the Conventional Commits specification:

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

<body>

<footer>

Types

  • feat: A new feature
  • fix: A bug fix
  • docs: Documentation changes
  • style: Code style changes (formatting, etc.)
  • refactor: Code refactoring
  • test: Adding or updating tests
  • chore: Maintenance tasks

Examples

feat(issues): add drag-and-drop to kanban board

- Implement drag-and-drop functionality for issue cards
- Add visual feedback during drag operation
- Update issue position on drop

Closes #123
fix(backend): resolve database connection timeout issue

- Increase connection pool size
- Add retry logic for failed connections
- Update error handling

Fixes #456
docs(readme): update installation instructions

- Add detailed setup steps
- Include troubleshooting section
- Add links to API documentation

Commit Best Practices

  • Keep commits atomic (one logical change per commit)
  • Write clear and descriptive commit messages
  • Reference issues when applicable
  • Use imperative mood in subject line ("add" not "added")
  • Limit subject line to 50 characters
  • Wrap body at 72 characters

🔄 Pull Request Process

Before Submitting

  1. Update your branch with latest from main:

    git fetch upstream
git rebase upstream/main

  2. Run tests and ensure they pass:

    # Backend
uv run pytest

# Frontend
npm test

  3. Check code quality:

    # Backend
uv run black src/
uv run flake8 src/

# Frontend
npx prettier --write "src/**/*.ts"
ng lint

  4. Test manually - Verify your changes work as expected

Creating PR

  1. Push to your fork:

    git push origin feature/your-feature

  2. Open Pull Request on GitHub

  3. Fill out PR template completely:

    • Clear title following commit message format
    • Detailed description of changes
    • Link to related issues
    • Screenshots if UI changes
    • Testing instructions

  4. Request review from maintainers

PR Guidelines

  • Keep PRs focused and small when possible
  • Address review feedback promptly
  • Be open to suggestions and improvements
  • Update PR description if scope changes

PR Checklist

Before submitting your PR, ensure:

  • Code follows project style guidelines
  • Tests are added/updated (if applicable)
  • All tests pass
  • Documentation is updated (if needed)
  • Commit messages follow conventions
  • No console errors or warnings
  • Responsive design works (for UI changes)
  • Accessibility considerations addressed

🐛 Bug Reports

Before Reporting

  • Check if issue already exists
  • Test with latest version
  • Try to reproduce consistently

Bug Report Template

When creating a bug report, include:

  • Title: Clear and descriptive
  • Description: What happened vs. what should happen
  • Steps to Reproduce: Detailed, numbered steps
  • Expected Behavior: What you expected
  • Actual Behavior: What actually happened
  • Environment:
    • OS: [e.g., Windows 10, macOS Big Sur]
    • Browser: [e.g., Chrome 96, Firefox 95]
    • Node.js version: [e.g., v16.13.0]
    • Python version: [e.g., 3.12.0]
  • Screenshots: If applicable
  • Logs: Error messages or stack traces

Example

**Title**: Issue cards disappear when dragged to "Done" column

**Description**: 
When dragging an issue card to the "Done" column on the kanban board, 
the card disappears instead of moving to the new column.

**Steps to Reproduce**:
1. Navigate to Board view
2. Find any issue in "To Do" column
3. Drag the issue card to "Done" column
4. Release the mouse

**Expected**: Card should move to "Done" column
**Actual**: Card disappears from the board

**Environment**:
- OS: Windows 11
- Browser: Chrome 120.0.6099.109
- Node.js: v18.19.0
- Python: 3.12.0

**Console Errors**:

ERROR TypeError: Cannot read properties of undefined (reading 'status')

✨ Feature Requests

Before Requesting

  • Check if feature already exists or is planned
  • Consider if it fits project scope
  • Think about implementation approach

Feature Request Template

  • Title: Clear description of the feature
  • Problem: What problem does this solve?
  • Solution: How should it work?
  • Alternatives: What alternatives have you considered?
  • Additional Context: Mockups, examples, references

Example

**Title**: Add bulk edit functionality for issues

**Problem**: 
Currently, updating multiple issues requires editing each one individually,
which is time-consuming for batch operations.

**Solution**:
Add a bulk edit mode where users can:
1. Select multiple issues via checkboxes
2. Click "Bulk Edit" button
3. Update common fields (assignee, priority, sprint, etc.)
4. Apply changes to all selected issues

**Alternatives Considered**:
- Keyboard shortcuts for multi-select (less discoverable)
- CSV import/export (too complex for simple updates)

**Additional Context**:
Similar to JIRA's bulk change feature. Mockup attached.

📚 Questions?

If you have questions:

  • Check existing documentation
  • Search closed issues
  • Ask in GitHub Discussions (if enabled)
  • Join our community chat (if available)

🎉 Thank You!

Every contribution, no matter how small, helps make Chronos better. We appreciate your time and effort!

Back to main README