ISODroid/docs/CONTRIBUTING.md

Contributing to ISO Droid

This document explains how to contribute OS icons and download links to ISO Droid.

For building the app, see BUILDING.md.

Adding OS Icons

OS icons are displayed in the file browser when ISO/IMG filenames match the icon name.

Steps:

1. Add your SVG file to app/src/main/assets/osicons/

   • Filename should be lowercase (e.g., ubuntu.svg, archlinux.svg)
   • SVG should be simple and recognizable
   • Recommended: Get icons from Simple Icons

2. The app automatically detects and matches icons:

   • Filename ubuntu-22.04-desktop-amd64.iso → matches ubuntu.svg
   • Filename archlinux-2024.12.01-x86_64.iso → matches archlinux.svg
   • Matching is case-insensitive and searches for icon name within filename

3. Symlinks for filename variations:

   Sometimes ISO files use shortened or alternate names. Create symlinks to match these variations:

   cd app/src/main/assets/osicons/
   
   # Linux Mint ISOs often named "mint-*.iso"
   ln -s linuxmint.svg mint.svg
   
   # Windows ISOs might be "Win11.iso" or "Win.iso"
   ln -s windows.svg win.svg
   ln -s windows.svg win11.svg
   

   This ensures mint-21.3-cinnamon.iso matches even though the icon is linuxmint.svg

4. Submit a pull request with your new icon(s) and any necessary symlinks

Adding OS Download Links

The Downloads screen shows curated links to operating system ISOs.

Steps:

1. Edit app/src/main/assets/os.json

2. Add a new entry with all required fields:

{
  "name": "Ubuntu Desktop",
  "category": "Linux",
  "description": "Popular Linux distribution with GNOME desktop",
  "icon": "ubuntu.svg",
  "url": "https://ubuntu.com/download/desktop"
}

Field descriptions:

• name (required): Display name for the OS
• category (required): One of: Linux, BSD, Windows, or Recovery
• description (required): Brief description (one sentence)
• icon (required): Filename of SVG in osicons/ directory, or null if no icon
• url (required): Direct link to download page or ISO file

Example with no icon:

{
  "name": "Custom Linux",
  "category": "Linux",
  "description": "A custom Linux distribution",
  "icon": null,
  "url": "https://example.com/download"
}

3. Test your changes:

   • Build the app (see BUILDING.md)
   • Navigate to Downloads screen
   • Verify your entry appears in the correct category
   • Verify the icon displays (if provided)
   • Verify the link opens correctly

4. Submit a pull request with:

   • Updated os.json
   • New SVG icon in osicons/ (if applicable)
   • Brief description of what you added

Testing

Before submitting a PR, test on a real rooted Android device:

• App builds successfully
• New OS icon displays correctly
• New download link opens properly
• No crashes or errors in logcat