spring cleaning and refactoring
This commit is contained in:
Richard Macias
236
CONTRIBUTING.md
Normal file
236
CONTRIBUTING.md
Normal file
@@ -0,0 +1,236 @@
|
||||
# Contributing
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- Python 3.11+
|
||||
- Make (optional, but recommended)
|
||||
- Git
|
||||
|
||||
## Quick Start
|
||||
|
||||
```bash
|
||||
# Clone the repository
|
||||
git clone https://github.com/RJNY/Obtainium-Emulation-Pack.git
|
||||
cd Obtainium-Emulation-Pack
|
||||
|
||||
# Make your changes to src/applications.json (or use make add-app)
|
||||
make validate # check for structural errors
|
||||
make test # verify configs resolve to real APKs
|
||||
make release # normalize, regenerate README, build release JSONs
|
||||
```
|
||||
|
||||
## Project Structure
|
||||
|
||||
```
|
||||
src/
|
||||
applications.json # Source of truth - all app definitions
|
||||
scripts/
|
||||
validate-json.py # Validates applications.json
|
||||
test-apps.py # Live-tests configs resolve to downloadable APKs
|
||||
add-app.py # Interactive CLI to add a new app
|
||||
generate-table.py # Generates the README table
|
||||
generate-readme.py # Stitches markdown files into README
|
||||
minify-json.py # Creates release JSON files
|
||||
normalize-json.py # Normalize key order and backfill defaults
|
||||
release.py # Automated release workflow (tag, push, gh release)
|
||||
constants.py # Shared constants and Obtainium source schema
|
||||
utils.py # Shared utility functions and .env loader
|
||||
pages/
|
||||
header.md # README header/intro
|
||||
table.md # Generated - app tables (do not edit)
|
||||
faq.md # FAQ section
|
||||
footer.md # Short section linking here (stitched into README)
|
||||
obtainium-emulation-pack-latest.json # Standard release
|
||||
obtainium-emulation-pack-dual-screen-latest.json # Dual-screen release
|
||||
```
|
||||
|
||||
## Adding a New Application
|
||||
|
||||
### Option A: Quick Add (Recommended for GitHub apps)
|
||||
|
||||
Use the interactive CLI to quickly add a new app:
|
||||
|
||||
```bash
|
||||
make add-app
|
||||
```
|
||||
|
||||
This will:
|
||||
|
||||
- Prompt you for the GitHub URL
|
||||
- Auto-detect the source, author, and app name
|
||||
- Ask for the Android package ID and category
|
||||
- Generate proper Obtainium settings
|
||||
- Add the app to `applications.json`
|
||||
|
||||
> **Tip:** To find the package ID, open the app in Obtainium - the package ID is displayed directly below the source URL (e.g., `com.example.android`).
|
||||
|
||||
After running, execute `make release` to regenerate all files.
|
||||
|
||||
### Option B: Manual Add (For complex configs or non-GitHub sources)
|
||||
|
||||
#### Step 1: Export the app config from Obtainium
|
||||
|
||||
1. Open Obtainium on your device
|
||||
2. Add the app you want to include (configure it how you want)
|
||||
3. Long-press the app and select "Export"
|
||||
4. Choose "Obtainium Export" format
|
||||
5. Transfer the JSON to your computer
|
||||
|
||||
#### Step 2: Add the app to applications.json
|
||||
|
||||
Open `src/applications.json` and add your app to the `apps` array:
|
||||
|
||||
```json
|
||||
{
|
||||
"id": "com.example.emulator",
|
||||
"url": "https://github.com/example/emulator",
|
||||
"author": "example",
|
||||
"name": "Example Emulator",
|
||||
"preferredApkIndex": 0,
|
||||
"additionalSettings": "{...}",
|
||||
"categories": ["Emulator"],
|
||||
"overrideSource": "GitHub"
|
||||
}
|
||||
```
|
||||
|
||||
#### Step 3: Add meta fields (optional)
|
||||
|
||||
Add a `meta` object to customize how the app appears:
|
||||
|
||||
```json
|
||||
{
|
||||
"id": "com.example.emulator",
|
||||
"url": "https://github.com/example/emulator",
|
||||
"author": "example",
|
||||
"name": "Example Emulator",
|
||||
"preferredApkIndex": 0,
|
||||
"additionalSettings": "{...}",
|
||||
"categories": ["Emulator"],
|
||||
"overrideSource": "GitHub",
|
||||
"meta": {
|
||||
"nameOverride": "Example Emu",
|
||||
"urlOverride": "https://example-emu.org"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### Step 4: Validate, test, and regenerate
|
||||
|
||||
```bash
|
||||
make validate # check for structural errors
|
||||
make test # verify your app config resolves to a real APK
|
||||
make release # normalize, regenerate README, build release JSONs
|
||||
```
|
||||
|
||||
## Pre-Commit Checklist
|
||||
|
||||
Before committing, run `make test` and `make release`, then verify:
|
||||
|
||||
- [ ] `make test` passes (all app configs resolve to downloadable APKs)
|
||||
- [ ] `obtainium-emulation-pack-latest.json` has been updated
|
||||
- [ ] `obtainium-emulation-pack-dual-screen-latest.json` has been updated
|
||||
- [ ] `README.md` has been updated
|
||||
- [ ] The README table shows a friendly application name (use `nameOverride` if not)
|
||||
- [ ] The README table links to the correct homepage (use `urlOverride` if not)
|
||||
- [ ] Beta apps are excluded with `meta.excludeFromExport: true`
|
||||
|
||||
## Available Make Commands
|
||||
|
||||
| Command | Description |
|
||||
| -------------------------------- | ----------------------------------------------------------- |
|
||||
| `make help` | Show all available commands |
|
||||
| `make add-app` | Interactive CLI to add a new app |
|
||||
| `make validate` | Validate applications.json (structure, regex, source types) |
|
||||
| `make test` | Live-test all app configs resolve to downloadable APKs |
|
||||
| `make test-app APP=name` | Live-test a single app by name (partial match) |
|
||||
| `make test-verbose` | Live-test all apps with APK URL details |
|
||||
| `make release` | Full pipeline: validate, normalize, readme, both JSONs |
|
||||
| `make normalize` | Normalize key order and backfill defaults |
|
||||
| `make table` | Generate the README table only |
|
||||
| `make readme` | Generate README.md from pages |
|
||||
| `make minify` | Generate standard release JSON |
|
||||
| `make minify-dual-screen` | Generate dual-screen release JSON |
|
||||
| `make publish` | Tag, push, and create a GitHub release |
|
||||
| `make publish-dry-run` | Preview release notes without publishing |
|
||||
| `make publish-from-file FILE=..` | Publish using a previously edited release notes file |
|
||||
|
||||
## Meta Field Reference
|
||||
|
||||
These fields in the `meta` object control how apps are processed:
|
||||
|
||||
| Field | Type | Default | Description |
|
||||
| --------------------- | ------ | ------- | ------------------------------------------------------------------- |
|
||||
| `excludeFromExport` | bool | `false` | Exclude from both release JSON files. Use for beta/unstable apps. |
|
||||
| `excludeFromTable` | bool | `false` | Exclude from the README table. |
|
||||
| `includeInStandard` | bool | `true` | Include in standard release. Set `false` for dual-screen-only apps. |
|
||||
| `includeInDualScreen` | bool | `true` | Include in dual-screen release. Set `false` for standard-only apps. |
|
||||
| `nameOverride` | string | `null` | Override the display name in the README table. |
|
||||
| `urlOverride` | string | `null` | Override the homepage link in the README table. |
|
||||
|
||||
## Categories
|
||||
|
||||
Apps are organized into categories that appear as sections in the README table:
|
||||
|
||||
| Category | Description |
|
||||
| -------------- | ---------------------------------------------------------------- |
|
||||
| `Emulator` | Console/handheld emulators (Dolphin, RetroArch, PPSSPP, etc.) |
|
||||
| `Frontend` | Emulator launchers and game library managers (Daijisho, Pegasus) |
|
||||
| `Utilities` | Helper apps (Syncthing, OdinTools, LED controllers, etc.) |
|
||||
| `PC Emulation` | Windows/PC game layers (Winlator, etc.) |
|
||||
| `Streaming` | Game streaming clients (Moonlight, etc.) |
|
||||
| `Track Only` | Version tracking without APK downloads (drivers, meta-packages) |
|
||||
|
||||
An app can belong to multiple categories.
|
||||
|
||||
## Dual-Screen vs Standard
|
||||
|
||||
The pack supports two variants:
|
||||
|
||||
- **Standard** (`obtainium-emulation-pack-latest.json`): For regular Android devices
|
||||
- **Dual-Screen** (`obtainium-emulation-pack-dual-screen-latest.json`): For dual-screen devices like LG V60/Velvet
|
||||
|
||||
Some apps have dual-screen-specific forks (e.g., Cemu, MelonDS). Use the `includeInStandard` and `includeInDualScreen` flags to control which variant(s) include each app.
|
||||
|
||||
**Why this matters:** Apps with the same Android package ID (`id` field) will conflict in Obtainium. If two apps share an ID (like standard Cemu and dual-screen Cemu), they **must not** both appear in the same JSON file.
|
||||
|
||||
Example: Standard Cemu excluded from dual-screen, dual-screen fork excluded from standard:
|
||||
|
||||
```json
|
||||
// Standard Cemu - exclude from dual-screen JSON
|
||||
{
|
||||
"id": "info.cemu.cemu",
|
||||
"name": "Cemu",
|
||||
"url": "https://github.com/SSimco/Cemu",
|
||||
"categories": ["Emulator"],
|
||||
"meta": { "includeInDualScreen": false }
|
||||
}
|
||||
|
||||
// Dual-screen Cemu fork - exclude from standard JSON
|
||||
{
|
||||
"id": "info.cemu.cemu",
|
||||
"name": "Cemu",
|
||||
"url": "https://github.com/SapphireRhodonite/Cemu",
|
||||
"categories": ["Dual Screen"],
|
||||
"meta": { "includeInStandard": false }
|
||||
}
|
||||
```
|
||||
|
||||
## Choosing the Right Category and Variant
|
||||
|
||||
Use this decision tree:
|
||||
|
||||
1. **Is this app device-specific?** (e.g., AYN Thor frontend)
|
||||
|
||||
- Yes: Set `includeInStandard: false` and use appropriate category
|
||||
- No: Continue to step 2
|
||||
|
||||
2. **Does this app share an ID with another app in the pack?** (e.g., forks, beta builds, dual-screen variants)
|
||||
|
||||
- Yes: Only one app per ID can be in each release JSON. Options:
|
||||
- Use `includeInStandard`/`includeInDualScreen` to split between variants
|
||||
- Use `excludeFromExport: true` on the less stable version (e.g., nightly builds)
|
||||
- No: App can be in both variants (default)
|
||||
|
||||
3. **Is this app stable and ready for users?**
|
||||
- Yes: Include normally
|
||||
- No: Set `excludeFromExport: true` (still visible in table but not in release JSONs)
|
||||
Reference in New Issue
Block a user