aidanpark--openclaw-android/CONTRIBUTING.md

Contributing to OpenClaw on Android

Thanks for your interest in contributing! This guide will help you get started.

First-Time Contributors

Welcome — contributions of all sizes are valued. If this is your first contribution:

1. Find an issue. Look for issues labeled good first issue — these are scoped for newcomers.

2. Pick a scope. Good first contributions include:

   • Typo and documentation fixes
   • Shell script improvements
   • Bug fixes with clear reproduction steps

3. Follow the fork → PR workflow described below.

Development Setup

Shell Scripts (installer, updater, patches)

# Clone the repo
git clone https://github.com/AidanPark/openclaw-android.git
cd openclaw-android

# Validate shell scripts
bash -n install.sh
bash -n update-core.sh
bash -n oa.sh

Shell scripts follow POSIX-compatible style with 4-space indentation. See scripts/lib.sh for shared conventions.

Android App

cd android

# Build APK
./gradlew assembleDebug

# Run lint checks
./gradlew ktlintCheck
./gradlew detekt

# Format code
./gradlew ktlintFormat

Prerequisites: JDK 21, Android SDK (API 28+), NDK 28+, Node.js 22+ (for WebView UI).

WebView UI

cd android/www
npm install
npm run build

Enable Git Hooks

git config core.hooksPath .githooks

This enables the pre-commit hook that automatically runs before every commit:

• Kotlin: ktlint (formatting) + detekt (static analysis)
• Shell scripts: shellcheck (requires shellcheck installed)
• Markdown: markdownlint (requires markdownlint-cli2 installed)
• WebView: ESLint on TypeScript/React files in android/www/
• Sync check: Verifies post-setup.sh root and app assets are identical

How to Contribute

1. Fork and Clone

git clone https://github.com/<your-username>/openclaw-android.git
cd openclaw-android

2. Make Your Changes

All work happens on main — we use a single-branch workflow with no prefixes.

3. Test Your Changes

• Shell scripts: Run bash -n <script> to validate syntax
• Android app: Run ./gradlew assembleDebug to verify build
• Kotlin code: Run ./gradlew ktlintCheck && ./gradlew detekt

4. Commit

Commit messages use English, imperative style, with no prefix:

Fix update-core.sh syntax error
Add multi-session terminal tab bar
Upgrade Node.js to v22.22.0 for FTS5 support

• Start with a capital letter, no period at the end
• Keep the subject line under 50 characters
• Use imperative present tense ("Fix", not "Fixed" or "Fixes")

5. Open a Pull Request

Open a PR against main. Describe:

• What the change does
• Why it's needed
• How to test it

Project Structure

The project has two main parts:

• Shell scripts (root) — Installer, updater, patches, CLI. These run in Termux on Android.
• Android app (android/) — Kotlin/Android APK with WebView UI and native terminal.

See the README for the full project structure and architecture details.

Code Style

Language	Style	Indentation
Shell (bash)	POSIX compatible, scripts/lib.sh conventions	4 spaces
Kotlin	Official coding conventions	4 spaces
XML	Standard Android conventions	2 spaces
TypeScript/React	ESLint config in android/www/	2 spaces

Key Considerations

When contributing to this project, keep in mind:

• Termux compatibility — Scripts must work in Termux's environment ($PREFIX paths, no root)
• glibc boundary — Node.js runs under glibc-runner while system tools use Bionic libc
• Path handling — Standard Linux paths (/tmp, /bin/sh) must be converted to Termux equivalents
• Android version range — The app targets minSdk 24 (Android 7.0) to targetSdk 28
• Idempotency — Install and update scripts should be safe to run multiple times

Reporting Issues

• Bugs: Include Android version, device model, Termux version, steps to reproduce
• Features: Describe the use case and proposed approach
• Security: See SECURITY.md for responsible disclosure

License

By contributing, you agree that your contributions will be licensed under the MIT License.