wehub-resource-sync
152 lines
4.3 KiB
Markdown
152 lines
4.3 KiB
Markdown
# 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`](https://github.com/AidanPark/openclaw-android/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22) — 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)
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
cd android/www
|
|
npm install
|
|
npm run build
|
|
```
|
|
|
|
### Enable Git Hooks
|
|
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
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](README.md) 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](https://kotlinlang.org/docs/coding-conventions.html) | 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](SECURITY.md) for responsible disclosure
|
|
|
|
## License
|
|
|
|
By contributing, you agree that your contributions will be licensed under the MIT License.
|