Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
155 lines (108 loc) · 4.4 KB

CONTRIBUTING.md

File metadata and controls

155 lines (108 loc) · 4.4 KB

Contributing to DebugOverlay

Thank you for considering contributing to DebugOverlay! This document outlines how to contribute effectively.

Code of Conduct

  • Be respectful and constructive in discussions
  • Focus on the problem, not the person
  • Welcome newcomers and help them get started

Getting Started

Prerequisites

  • Android Studio Panda 2 (2025.3.2) or later
  • JDK 21+
  • Kotlin 2.2+
  • Basic knowledge of Jetpack Compose

Setup

  1. Fork the repository
  2. Clone your fork: 
    git clone https://github.com/YOUR_USERNAME/DebugOverlay-Android.git
cd DebugOverlay-Android
  3. Add the upstream remote: 
    git remote add upstream https://github.com/Manabu-GT/DebugOverlay-Android.git
  4. Open the project in Android Studio and sync Gradle

Optional: AI Tools Setup

If you use Claude Code, you can enable MCP servers for enhanced development:

cp .mcp.json.example .mcp.json

The example config includes:

  • Codex CLI – Code review assistance
  • android-mcp – Automated UI testing on connected Android devices/emulators

This is entirely optional and won't affect your ability to contribute.

How to Contribute

Reporting Bugs

Before creating an issue:

  1. Search existing issues to avoid duplicates
  2. Check GitHub Discussions for known problems

When ready, file a bug report.

Suggesting Features

Open a feature request issue.

Pull Requests

  1. Create an issue first for significant changes to discuss the approach
  2. Branch from main using the naming conventions below
  3. Keep changes focused — one feature or fix per PR
  4. Write tests for new functionality (see Testing)
  5. Update documentation if needed
  6. Run checks before submitting: 
    ./gradlew spotlessApply  # Format code (must run before check)
./gradlew check          # Run all checks (tests, lint, detekt, spotless)

Branch Naming

Prefix Use Case
feature/ New features
fix/ Bug fixes
docs/ Documentation only
refactor/ Code restructuring
test/ Test additions

Example: feature/add-memory-tracking, fix/overlay-crash-on-rotate

Commit Messages

Follow Conventional Commits:

type(scope): description

[optional body]

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

Scopes: core, overlay, okhttp, timber, sample, build

Examples:

feat(core): add CPU usage tracking module
fix(overlay): prevent crash when activity is destroyed
docs(readme): update installation instructions

Code Style

See Coding Conventions for detailed guidelines. Also see Build & Gradle for toolchain and module conventions.

Key points:

  • All new code in Kotlin
  • 4-space indentation
  • Run ./gradlew spotlessApply before committing
  • Use runCatchingNonCancellation in suspend functions

Testing

See Testing for detailed guidelines. For code review standards, see Code Review.

# All checks
./gradlew check

# Specific module
./gradlew :debugoverlay-core:check

Code Coverage

To generate a local code coverage report for non-UI code (merging all library modules):

./gradlew mergedJacocoReport

The report will be available at build/reports/jacoco/mergedJacocoReport/html/index.html.

Project Structure

Module Description
debugoverlay-core Compose-based runtime and shared components
debugoverlay Primary public API
debugoverlay-extension-okhttp OkHttp interceptor for network tracking
debugoverlay-extension-timber Timber tree for log capture
sample Demo application

Questions?

Thank you for contributing!