Contributing¶

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

Getting Started¶

Fork the repository on GitHub
Clone your fork locally
Create a branch for your changes
Make your changes
Push to your fork
Submit a pull request

Development Setup¶

Prerequisites¶

Python 3.6 or higher
pip package manager
git

Installation¶

# 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:

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

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 Architecture)

Submitting Changes¶

Pull Request Process¶

Update your fork:

git fetch upstream
git rebase upstream/main

Run all checks:
```
make test
make lint-all
```
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).