crkl/CONTRIBUTING.md

# Contribution Guide

Thank you for contributing to **Circle** (repo `crkl`).

## Getting Started

### Prerequisites

- Android Studio (latest stable version)
- JDK 17 (see Makefile / Homebrew `openjdk@17`)
- Git
- Kotlin + Jetpack Compose familiarity

### Development Setup

1. **Clone the repository:**
   ```bash
   git clone https://git.levkin.ca/ilia/crkl.git
   cd crkl
   ```

2. **Open in Android Studio** (or use `./gradlew` + Makefile).

3. **Review documentation:**
   - [README.md](README.md) — overview
   - [docs/](docs/) — ship, shortcuts, brand
   - [ARCHITECTURE.md](ARCHITECTURE.md) — technical layers
   - Check `.notes/` directory for current project context
   - Review `CURSOR_SUPPORT.md` if using Cursor editor

4. **Build the project:**
   ```bash
   ./gradlew build
   ```

## Contribution Workflow

### 1. Issue Tracking

- Use OpenProject for issue/ticket tracking and milestone definitions
- Check existing issues before creating new ones
- Reference issue numbers in commits and pull requests

### 2. Branching Strategy

- `main` - stable release branch
- `develop` - integration branch for features
- `feature/*` - feature development branches
- `bugfix/*` - bug fix branches
- `hotfix/*` - urgent production fixes

### 3. Making Changes

1. **Create a feature branch:**
   ```bash
   git checkout -b feature/your-feature-name
   ```

2. **Follow coding conventions:**
   - Use Kotlin for all Android code
   - Follow Kotlin coding conventions
   - Use Jetpack Compose for UI components
   - Ensure all ML operations are asynchronous
   - Never add network calls or cloud service dependencies
   - Document module purpose in file headers

3. **Write tests:**
   - Add unit tests for new functionality
   - Ensure existing tests pass
   - Aim for good test coverage

4. **Document your changes:**
   - Update relevant documentation in `.notes/`
   - Add code comments for complex logic
   - Reference ticket IDs in TODOs
   - Update `ARCHITECTURE.md` for architectural changes

### 4. Submitting Changes

1. **Commit your changes:**
   ```bash
   git add .
   git commit -m "Brief description of changes (refs #issue-number)"
   ```

2. **Push to your fork:**
   ```bash
   git push origin feature/your-feature-name
   ```

3. **Create a Pull Request:**
   - Provide clear description of changes
   - Reference related issues
   - Ensure CI checks pass
   - Request review from maintainers

## Code Style and Standards

### Kotlin Style Guide

- Follow [Kotlin Coding Conventions](https://kotlinlang.org/docs/coding-conventions.html)
- Use meaningful variable and function names
- Keep functions small and focused
- Prefer immutability where possible

### Module Organization

Refer to `.notes/directory_structure.md` for module organization:

- `/src/accessibility/` - Accessibility overlay and services
- `/src/gesture/` - Gesture tracking, region extraction
- `/src/model/` - STT/LLM wrappers, inference runners
- `/src/vision/` - Content classification and ML components
- `/src/agent/` - Dialogue state management
- `/src/ui/` - Jetpack Compose overlays and feedback UIs
- `/src/privacy/` - Data/cache handling, controls

### Documentation Standards

- Document public APIs with KDoc comments
- Include usage examples for complex functions
- Update README and ARCHITECTURE docs for significant changes
- Keep `.notes/` directory current for AI/contributor context

### Testing Guidelines

- Write unit tests for business logic
- Write integration tests for module interactions
- Test on multiple Android versions and device types
- Test accessibility features thoroughly
- Document test coverage in `TESTING.md` (to be created)

## Privacy and Security Requirements

**Critical:** All contributions must adhere to privacy-first principles:

- DO: Use local-only processing
- DO: Keep all data on device
- DO: Use offline ML models
- DON'T: Add network calls for AI features
- DON'T: Send data to external services
- DON'T: Include cloud service dependencies

## Review Process

1. **Automated Checks:**
   - Code builds successfully
   - Tests pass
   - Linting passes
   - No new warnings

2. **Code Review:**
   - At least one maintainer approval required
   - Address review feedback
   - Maintain respectful communication

3. **Merge:**
   - Squash commits if needed
   - Ensure clean commit history
   - Update changelog

## Communication

- **Issues:** Use GitHub Issues or OpenProject for bug reports and feature requests
- **Discussions:** Use GitHub Discussions for questions and ideas
- **Pull Requests:** Use PR comments for code-specific discussions

## Milestones and Roadmap

### Milestone 1: Proof of Concept (POC)
- Accessibility overlay service with region selection
- Region processor for gesture-to-area conversion
- Integration of local speech-to-text
- Integration of open-source LLM module
- Basic Compose overlay UI

### Milestone 2: Minimum Viable Product (MVP)
- POC modules integrated
- Persistent dialogue management
- Voice command routing
- Core session memory and privacy controls
- Initial bug triage and test coverage

### Milestone 3: Full Feature Release
- Advanced content classification
- Plugin/module system
- Export/import settings
- Issue triage and contributor merge pass

## Recognition

Contributors will be recognized in:
- CONTRIBUTORS.md file
- Release notes
- Project documentation

Thank you for contributing to Circle!