# Flathub Submission Files

This directory contains files for submitting PDFApps to [Flathub](https://flathub.org/).

## ⚠️ Important: Read Before Submitting

Flathub has a strict policy against AI-generated submissions. **You must:**

1. **Test the build locally** on a real Linux machine before opening a PR
2. **Write the PR description yourself** in plain prose — do not paste AI-generated text
3. **Keep the Flathub PR template intact** and fill it manually
4. **Branch from `new-pr`** in your fork (not `master`)
5. **Disable Copilot code review** on your `flathub` fork
6. Run `flatpak-builder-lint` and resolve **all** warnings

A previous AI-assisted PR (#8301) was closed by a maintainer. Repeat offenses can lead to a permanent ban.

## Files

- `io.github.nelsonduarte.PDFApps.yml` — Flatpak manifest (KDE Platform 6.8)
- `python-modules.yml` — Python deps with SHA256 (generated by `req2flatpak`)
- `io.github.nelsonduarte.PDFApps.metainfo.xml` — AppStream metadata
- `io.github.nelsonduarte.PDFApps.desktop` — Desktop entry
- `flathub.json` — Restrict to `x86_64` (PySide6 wheels limitation)
- `pdfapps.sh` — Launcher script
- `requirements-pinned.txt` — Pinned versions used to generate `python-modules.yml`

## Local build (REQUIRED before submission)

```bash
# Install on Ubuntu/Debian
sudo apt install flatpak flatpak-builder

# Add Flathub remote
flatpak remote-add --if-not-exists --user flathub https://flathub.org/repo/flathub.flatpakrepo

# Install KDE runtime + SDK
flatpak install --user flathub org.kde.Platform//6.8 org.kde.Sdk//6.8

# Install the official builder + linter
flatpak install --user flathub org.flatpak.Builder

# Build (from repo root, NOT from flatpak/)
flatpak run org.flatpak.Builder --force-clean --user --install \
  --install-deps-from=flathub --repo=repo builddir \
  flatpak/io.github.nelsonduarte.PDFApps.yml

# Run the lint
flatpak run --command=flatpak-builder-lint org.flatpak.Builder \
  manifest flatpak/io.github.nelsonduarte.PDFApps.yml

flatpak run --command=flatpak-builder-lint org.flatpak.Builder \
  appstream flatpak/io.github.nelsonduarte.PDFApps.metainfo.xml

# If the build succeeds, run it
flatpak run io.github.nelsonduarte.PDFApps
```

## Submission process

1. Fork [flathub/flathub](https://github.com/flathub/flathub) on GitHub
2. **Disable** GitHub Copilot code review on your fork
3. Clone the fork and check out the `new-pr` branch:
   ```bash
   git clone https://github.com/<you>/flathub.git
   cd flathub
   git checkout new-pr
   ```
4. Copy these files to the **root** of your fork:
   - `io.github.nelsonduarte.PDFApps.yml`
   - `python-modules.yml`
   - `flathub.json`
   - The `metainfo.xml`, `desktop`, and `pdfapps.sh` are referenced by the manifest from the source repo, so they don't need to be in the flathub repo
5. Commit and push to your fork
6. Open a PR targeting `flathub/flathub:new-pr`
7. **Fill the PR template manually** — do not generate the description with AI
8. Wait for the build bots, then for human review

## Notes

- **App-ID**: `io.github.nelsonduarte.PDFApps` follows reverse-DNS convention (lowercase domain part, PascalCase product name is allowed)
- **Auto-updater**: disabled inside Flatpak via `FLATPAK_ID` env var detection
- **Tesseract / Ghostscript**: NOT bundled. OCR and advanced compression require system installs (limitation of the sandbox model)
- **Architecture**: `x86_64` only (PySide6 doesn't ship aarch64 wheels for all dependencies)
- **License**: MIT, installed to `/app/share/licenses/io.github.nelsonduarte.PDFApps/LICENSE`
