android-kiosk-browser/CONTRIBUTING.md

Contributing to Android Kiosk Browser

Thank you for your interest in contributing! This document provides guidelines for contributing to the project.

Getting Started

Prerequisites

• Android Studio (latest stable)
• JDK 17+
• Android SDK (API 21+)
• Git

Setup

# Clone the repository
git clone https://git.hobbs.farm/pluto/android-kiosk-browser.git
cd android-kiosk-browser

# Open in Android Studio
# File → Open → select project directory

# Build
./gradlew build

# Run tests
./gradlew test

Development Workflow

Branching Strategy

• main — Stable release branch
• feature/* — New features
• fix/* — Bug fixes
• docs/* — Documentation updates

Making Changes

1. Create a branch

   git checkout -b feature/your-feature-name
   

2. Make your changes

   • Follow existing code style (Kotlin conventions)
   • Add tests for new functionality
   • Update documentation as needed

3. Test your changes

   ./gradlew test
   ./gradlew lint
   

4. Commit with clear messages

   git commit -m "feat: Add new whitelist import feature"
   

5. Push and create a PR

   git push origin feature/your-feature-name
   

Commit Message Format

Use conventional commits:

• feat: New feature
• fix: Bug fix
• docs: Documentation only
• test: Adding/updating tests
• refactor: Code refactoring
• chore: Maintenance tasks

Code Guidelines

Kotlin Style

• Use Kotlin idioms (let, apply, etc.)
• Prefer immutability (val over var)
• Use meaningful variable names
• Keep functions small and focused

Testing

• All new features need unit tests
• Security-related code needs extra test coverage
• Run the full test suite before submitting

Security

• Never store sensitive data in plain text
• Validate all user inputs
• Test for bypass vulnerabilities (see WhitelistTest.kt)

Project Structure

app/src/main/
├── java/farm/hobbs/kioskbrowser/
│   ├── KioskActivity.kt      # Main WebView activity
│   ├── AdminActivity.kt      # Settings panel
│   ├── BootReceiver.kt       # Auto-start on boot
│   └── KioskDeviceAdminReceiver.kt
└── res/
    ├── layout/               # UI layouts
    ├── values/               # Strings, themes
    └── xml/                  # Device admin config

app/src/test/
└── kotlin/farm/hobbs/kioskbrowser/
    ├── WhitelistTest.kt
    ├── IdleTimerTest.kt
    └── ConfigValidationTest.kt

Reporting Issues

Use Vikunja (vikunja.hobbs.farm) for issue tracking:

• P0 — Critical/security issues
• P1 — Important features/bugs
• P2 — Nice-to-have improvements

Questions?

Reach out to the team:

• Pluto 🪐 — Project coordination, infrastructure
• Spirit 👻 — Testing, code review
• Margaret 🌸 — Documentation, requirements

---

Happy contributing! 🚀