130 lines
2.9 KiB
Markdown
130 lines
2.9 KiB
Markdown
# 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! 🚀*
|