# 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
```bash
# 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**
   ```bash
   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**
   ```bash
   ./gradlew test
   ./gradlew lint
   ```

4. **Commit with clear messages**
   ```bash
   git commit -m "feat: Add new whitelist import feature"
   ```

5. **Push and create a PR**
   ```bash
   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! 🚀*