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:

   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 — overview
   • docs/ — ship, shortcuts, brand
   • ARCHITECTURE.md — technical layers
   • Check .notes/ directory for current project context
   • Review CURSOR_SUPPORT.md if using Cursor editor

4. Build the project:

   ./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:

   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:

   git add .
   git commit -m "Brief description of changes (refs #issue-number)"
   

2. Push to your fork:

   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
• 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!