Contributing
============

Thank you for your interest in contributing to jott! This guide covers the
development workflow.

Getting Started
---------------

1. Fork the repository on GitHub
2. Clone your fork locally
3. Create a branch for your changes
4. Make your changes
5. Push to your fork
6. Submit a pull request

Development Setup
-----------------

Prerequisites
~~~~~~~~~~~~~

- Python 3.6 or higher
- pip package manager
- git

Installation
~~~~~~~~~~~~

.. code-block:: bash

   # Clone your fork
   git clone https://github.com/YOUR_USERNAME/jot.git
   cd jot

   # Create a virtual environment
   python3 -m venv venv
   source venv/bin/activate

   # Install with development dependencies
   pip install -e ".[dev]"

   # Verify installation
   jott --version

Optional dependencies:

.. code-block:: bash

   pip install -e ".[mcp]"   # MCP server
   pip install -e ".[tts]"   # Text-to-speech
   pip install -e ".[docs]"  # Documentation

Branch Naming
-------------

Use descriptive branch names:

- ``feature/add-multi-select`` — new features
- ``fix/duplicate-task-ids`` — bug fixes
- ``docs/update-readme`` — documentation
- ``refactor/task-manager`` — code refactoring

Commit Messages
---------------

- Use imperative mood: "Add feature" not "Added feature"
- Capitalize the first letter
- No period at the end
- Reference issues when applicable (``#123``)

Examples::

   Add fuzzy search for task filtering
   Fix duplicate ID generation bug (#45)
   Update installation documentation
   Refactor keyboard handler for better testability

Code Style
----------

The project follows PEP 8 with customizations:

- **Line length**: 100 characters
- **String quotes**: Single quotes preferred
- **Import sorting**: isort with black profile
- **Formatter**: black

.. code-block:: bash

   make format       # Auto-format with black
   make format-check # Check formatting
   make lint         # Run flake8
   make lint-all     # Run all linters

Key style points:

- Use type hints where appropriate
- Write docstrings for public functions and classes (Google style)
- Keep functions focused and single-purpose
- Keep files under 300 lines (see :doc:`architecture`)

Submitting Changes
------------------

Pull Request Process
~~~~~~~~~~~~~~~~~~~~

1. Update your fork:

   .. code-block:: bash

      git fetch upstream
      git rebase upstream/main

2. Run all checks:

   .. code-block:: bash

      make test
      make lint-all

3. Push and create pull request with:

   - Clear title and description
   - Related issue references
   - Screenshots for UI changes

Pull Request Checklist
~~~~~~~~~~~~~~~~~~~~~~

- Tests pass (``make test``)
- Code is formatted (``make format``)
- Linting passes (``make lint-all``)
- Documentation is updated
- CHANGELOG.md updated for significant changes
- No sensitive information included

Reporting Issues
----------------

Bug Reports
~~~~~~~~~~~

Include: description, steps to reproduce, expected vs actual behavior,
environment info (OS, Python version, jott version), and relevant logs.

Feature Requests
~~~~~~~~~~~~~~~~

Include: use case, proposed solution, alternatives considered, and any
additional context (screenshots, mockups).