Adding a compatibility report

Every app has one Markdown file in docs/_apps, named by its Darwin platform and bundle identifier: docs/_apps/<platform>/<bundle id>.md, such as docs/_apps/ios/com.hulu.plus.md. The platform and bundle ID together are the app’s identifier, since an iOS app and a Mac app can share a bundle ID. Read the bundle ID from the app’s Info.plist (CFBundleIdentifier). Each report in the file comes from a merged pull request. To add a report, open a pull request that changes Perry and adds or edits the app’s file in the same branch, or send a pull request with the file alone that links the pull request it reports on.

The file format

Structured data goes in YAML front matter; anything longer goes in the Markdown body. GitHub shows the front matter as a table when the file is opened, so the file reads well there too.

---
name: Hulu
bundle_id: "com.hulu.plus"  # CFBundleIdentifier, always quoted
platform: ios            # ios | macos | maccatalyst, the folder it is in
kind: app                # app | game
developer: Hulu          # only if a PR states it or it is unambiguous
tags: [Swift, ObjC]      # languages and engines; see the list below
reports:
  - pr: 216
    date: 2026-11-19     # the PR's merge date
    perry: "e9a46074"    # the merge commit, 8 characters, always quoted
    platform: ios        # the same as the app's platform
    cpu: arm64           # ios: arm64 | armv7 | armv6; macos: arm64 | x86_64 | i386; maccatalyst: arm64 | x86_64
    app_version: "8.1"   # only if the PR states it, always quoted
    hardware: Lenovo Duet 3  # the machine it ran on
    resolution: "1170x2532"  # the size it drew at, if stated: "WxH" pixels, or "WxH@S" points at a scale
    graphics: Metal      # the graphics API this run drew with, if known
    fps: 60              # games only: the frame rate in play, or a range such as "45-52"
    env:                 # environment variables it ran with, if any
      - "PERRY_OS_VERSION=18.0"
    args:                # options passed to perry before the app, if any
      - "--report"
    os: Debian sid       # the operating system that machine ran
    packaging: Packaging/ios/com.hulu.plus/linux  # the launcher folder it ran with, if any
    level: 2
    source: title        # title | body | screenshot | maintainer: what the level rests on
    notes: Reaches the Welcome screen.
    screenshots:
      - url: https://github.com/user-attachments/assets/00000000-0000-0000-0000-000000000000
        caption: Welcome screen
---

Optional notes in Markdown: known problems, the `PERRY_*` settings the app
needs, what was worked around. Leave the body empty if the PRs say nothing
more than the reports do.

Quoting

Levels

Level Name Assign when the PR says
1 Loads starts, then stops or crashes; “launch crash”, “start-up”, “toward”
2 First screen splash, welcome, sign-in, login, launcher, loading screen, title screen, bot check
3 Main content, major issues past sign-in or into a menu or game, with stated problems or no claim of being usable; “bring up”, “initial support”
4 Usable “playable”, “play”, “runs” with main content shown and only small issues named
5 Complete the PR states that everything tested works

Screenshots

Screenshots are never stored in this repository. Attach the image to the pull request on GitHub, then copy its URL into screenshots exactly as it appears there. Only these forms are accepted:

The image must load without signing in to GitHub. Don’t link an image that shows an email address, account name, real name, street address, phone number, precise location, device serial or message content. Keep at most three per report, and give each a caption of a few plain words.

Checking and building locally

The check script needs only Ruby’s standard library:

ruby Scripts/compatibility-check.rb

It names the file and the problem when a report is malformed, and prints the number of apps and reports when all is well.

To build and preview the site, with Ruby and Bundler installed:

cd docs
bundle install
bundle exec jekyll serve

Then open http://localhost:4000/Perry/.