TimeTracker/docs/development/CONTRIBUTING.md

Contributing to TimeTracker

Thank you for your interest in contributing to TimeTracker! This document provides guidelines and information for contributors.

Table of Contents

• Code of Conduct
• How Can I Contribute?
• Development Setup
• Pull Request Process
• Coding Standards
• Testing
• Reporting Bugs
• Feature Requests
• Questions and Discussion
• Terminology

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.

How Can I Contribute?

Reporting Bugs

• Use the GitHub issue tracker
• Include a clear and descriptive title
• Describe the exact steps to reproduce the bug
• Provide specific examples to demonstrate the steps
• Describe the behavior you observed after following the steps
• Explain which behavior you expected to see instead and why
• Include details about your configuration and environment

Suggesting Enhancements

• Use the GitHub issue tracker
• Provide a clear and descriptive title
• Describe the suggested enhancement in detail
• Explain why this enhancement would be useful
• List any similar features and applications

Pull Requests

• Fork the repository
• Create a feature branch (git checkout -b feature/amazing-feature)
• Make your changes
• Add tests for new functionality
• Ensure all tests pass
• Commit your changes (git commit -m 'Add amazing feature')
• Push to the branch (git push origin feature/amazing-feature)
• Open a Pull Request

Translations (no Git required)

Contributors who only want to fix wording can use the Translation improvement GitHub issue template, work in Crowdin (Drytrix TimeTracker), or follow CONTRIBUTING_TRANSLATIONS.md (spreadsheet option, maintainer workflow, crowdin.yml, Crowdin sync workflow). Developers adding new _('...') strings should run pybabel extract / update as described there.

Development Setup

Prerequisites

• Python 3.11 or higher
• Docker and Docker Compose (for containerized development)
• Git

Local Development

1. Clone the repository:

   git clone https://github.com/drytrix/TimeTracker.git
   cd TimeTracker
   

2. Create a virtual environment:

   python -m venv venv
   source venv/bin/activate  # On Windows: venv\Scripts\activate
   

3. Install dependencies:

   pip install -r requirements.txt
   

4. Set up environment variables:

   cp env.example .env
   # Edit .env with your development settings
   

5. Initialize the database:

   flask db upgrade
   

6. Run the development server:

   flask run
   

Docker Development

1. Build and start the containers:

   docker-compose up --build
   

2. Access the application:

   • Default (docker-compose.yml): https://localhost (self-signed cert; accept the browser warning).
   • For http://localhost:8080 instead, use: docker-compose -f docker-compose.example.yml up -d or docker-compose -f docker-compose.local-test.yml up -d (SQLite, no PostgreSQL).

Pull Request Process

1. Fork and Clone: Fork the repository and clone your fork locally
2. Create Branch: Create a feature branch from main
3. Make Changes: Implement your changes following the coding standards
4. Test: Ensure all tests pass and add new tests for new functionality
5. Commit: Write clear, descriptive commit messages
6. Push: Push your branch to your fork
7. Submit PR: Create a pull request with a clear description

Commit Message Format

Use conventional commit format:

type(scope): description

[optional body]

[optional footer]

Types: feat, fix, docs, style, refactor, test, chore

Examples:

• feat(timer): add automatic idle detection
• fix(auth): resolve session timeout issue
• docs(readme): update installation instructions

Coding Standards

Python

• Follow PEP 8 style guidelines
• Use type hints where appropriate
• Keep functions focused and single-purpose
• Write docstrings for all public functions and classes
• Maximum line length: 88 characters (use Black formatter)

Flask

• Use blueprints for route organization
• Keep route handlers thin, move business logic to models or services
• Use proper HTTP status codes
• Implement proper error handling

HTTP APIs (/api/v1 vs /api)

• New features for integrations (mobile, desktop, scripts, webhooks): implement under /api/v1 first, with scopes and updates to OpenAPI in app/routes/api_docs.py.
• /api/* session JSON (app/routes/api.py): reserve for same-origin web UI needs (browser cookie auth). Reuse code from app/services/ instead of duplicating v1 logic. If you add a session route that mirrors v1, document it and consider X-API-Deprecated plus a Link successor header (see app/utils/api_deprecation.py and docs/api/API_VERSIONING.md).
• Global search (GET /api/v1/search and GET /api/search): shared implementation in app/services/global_search_service.py (run_global_search). Change behavior there and keep REST_API.md in sync.

Database

• Use SQLAlchemy ORM for database operations
• Write migrations for schema changes
• Use proper indexing for performance
• Follow naming conventions for tables and columns

Frontend

• Use semantic HTML
• Follow accessibility guidelines
• Keep CSS organized and maintainable
• Use HTMX for dynamic interactions

Testing

Running Tests

# Run all tests
python -m pytest

# Run with coverage
python -m pytest --cov=app

# Run specific test file
python -m pytest tests/test_timer.py

Writing Tests

• Write tests for all new functionality
• Use descriptive test names
• Test both success and failure cases
• Mock external dependencies
• Use fixtures for common test data

Test Structure

tests/
├── conftest.py          # Shared fixtures
├── test_models/         # Model tests
├── test_routes/         # Route tests
├── test_utils/          # Utility function tests
└── integration/         # Integration tests

Reporting Bugs

When reporting bugs, please include:

• Environment: OS, Python version, browser (if applicable)
• Steps to Reproduce: Clear, numbered steps
• Expected Behavior: What you expected to happen
• Actual Behavior: What actually happened
• Screenshots: If applicable
• Logs: Any error messages or logs

Feature Requests

For feature requests:

• Explain the problem you're trying to solve
• Describe the proposed solution
• Provide use cases and examples
• Consider implementation complexity
• Discuss alternatives you've considered

Questions and Discussion

• Use GitHub Discussions for general questions
• Use GitHub Issues for bugs and feature requests
• Be respectful and constructive
• Search existing issues before creating new ones

Getting Help

If you need help:

1. Check the README.md for basic information
2. Search existing issues and discussions
3. Create a new issue or discussion
4. Join our community channels (if available)

Terminology

Use consistent terms in code, API, and user-facing copy: time entry / time entries, client, project, task, invoice. For full product and naming context, see the Product/UX Audit.

License

By contributing to TimeTracker, you agree that your contributions will be licensed under the same license as the project (GNU General Public License v3.0).

Recognition

Contributors will be recognized in:

• The project's README.md
• Release notes
• Contributor statistics on GitHub

Thank you for contributing to TimeTracker! 🚀