Skip to content

Latest commit

 

History

History
485 lines (460 loc) · 32.1 KB

AGENTS.md

File metadata and controls

485 lines (460 loc) · 32.1 KB

AGENTS.md

Notes for AI coding agents (and humans) working on this repository.

What this repository is

AppImageHub, the catalog of AppImages at https://appimage.github.io, built by GitHub Pages (Jekyll) from this repository.

  • data/<Name>: one file per application, submitted by contributors in PRs. Its first line is a download URL, a GitHub, Codeberg or GitLab repository URL, (optionally with #Channel at the end, for a repository with a release per channel), or a download directory (e.g. https://download.kde.org/stable/digikam/ or an openSUSE Build Service .../AppImage/ directory); nothing else is read.
  • database/<Name>/: generated by CI from the AppImage: .desktop file (with an [AppImageHub] section of X-AppImage-* keys), icon, screenshot.png, AppStream metainfo. Do not edit by hand.
  • apps/<Name>.md: generated by CI; YAML front matter that the Jekyll templates render. Do not edit by hand.
  • _layouts/, _includes/ (notably app_teaser.html, app_notes.html), feed.json, search.json: the site. app.html sets post = page, so app templates use post.desktop.AppImageHub.X-AppImage-* etc.

How testing a submission works

  1. .github/workflows/test.yml (on PRs and pushes touching data/**) runs code/worker.sh data/<Name> for each added or changed file, under a per-app timeout, on Xvfb:

    • downloads the AppImage (resolving GitHub, Codeberg or GitLab repository URLs via code/fetch-releases.sh (each forge's API, normalized to GitHub's releases shape), and directory URLs (ending with /) via code/fetch-listing.sh, which reads the server's directory listing (Apache/nginx), descends into the newest version directory and into linux/, bin/, appimage/ and the like, and writes the AppImages found in the same shape with the listing's dates; then code/find-appimage.sh picks the AppImage by rules (among them: the newest toolkit build, e.g. Qt6 over Qt5; and the channel asked for with #Channel at the end of the URL in data/, e.g. https://github.com/srevinsaju/Firefox-Appimage#ESR, independent of the name of the file: only releases or AppImages with that word in their tag or file name count, and it is an error if there are none; without a channel, those of the other channels (esr, nightly, beta, ...) are left out, so that the entries of a repository with a release per channel do not collide) and fails rather than guesses when several fit; a URL ending with / that is no listing is downloaded as it is), checks its type, mounts it with a separate runtime (never executes the AppImage's own runtime), runs appdir-lint.sh, finds the icon;
    • code/check-libc.sh: does it need a compatible C library on the host? (X-AppImage-Libc=none|bundled|host, X-AppImage-Runtime, X-AppImage-Self-Contained, X-AppImage-Glibc-Required=GLIBC_2.xx, stored with the prefix because YAML would turn 2.40 into the number 2.4; an upper bound, as not every library in an AppImage is necessarily loaded);
    • code/check-name.sh: rules for the name of the file in data/ (errors only for files a PR adds, STRICT=true; warnings otherwise), and remarks about the AppImage's file name; it also prints a NOTE: (shown under "Notes" in the test result, not a warning) for an all-lowercase name without Terminal=true in the desktop file, or a name with capitals with Terminal=true: all-lowercase names are typically command line tools; the publish workflow only shows a note that check-name.sh --note-text generates exactly;
    • code/check-names-agree.sh: a warning when the name of the repository, the AppImage's name and the README's headline (code/fetch-readme.sh) disagree within a tolerance (equal, one contains the other, or >= 80 % similar, ignoring case and punctuation); shown under "Names" and "Warnings" in the test result;
    • runs the application in firejail without network, waits 30 s, takes a screenshot of the active window;
    • system tray applications: only if the application showed no window (or exited) and code/tray-hint.sh finds a tray API in its files (Qt, GTK, libappindicator, Electron new Tray(, XEmbed, StatusNotifierItem), it runs it again with a tray (stalonetray, XEmbed). If its icon docks there, it clicks the icon and takes the window that opens, else right-clicks it and takes the tray and menu; check-screenshot.sh gets tray (no empty-window check) and a warning asks the maintainer to check it;
    • code/check-screenshot.sh: fails on an (almost) empty window or an error message found by OCR (tesseract), or text mostly in Chinese, Arabic, Cyrillic or Greek script (OCR with those models, confident words only; label error-not-english);
    • warns when the AppImage has no (or broken) update information;
    • writes database/ and apps/. links: in apps/<Name>.md (shown on the page and in feed.json) gets the repository and its releases for GitHub, Codeberg and GitLab entries, and otherwise a Download link to the URL in data/ if it stays valid for new versions (a download directory or a "latest" link: no version number in its path). On PRs it stops there; on master it commits the result ([ci skip]). Afterwards the workflow collects a pr-result artifact: PR number, screenshot (or screen capture on failure), code/diagnose.sh hints and the excerpt of the log around the first error, and the libc flags.
  2. .github/workflows/publish-pr-screenshot.yml runs on workflow_run of "Test" (from master, with write permissions, because PRs come from forks whose runs have a read-only token) and posts a new comment on the PR for every test run (earlier results stay as they were), marked <!-- appimagehub-test-result -->. Screenshots are uploaded as GitHub attachments with the SCREENSHOT_UPLOAD_TOKEN secret (classic PAT), falling back to assets of the ci-screenshots release, which it prunes. Renewing the token: see MAINTAINER.md. It also sets red error-* labels on the PR for the known causes of a failed test (defined next to the hints in code/diagnose.sh, which holds triples of pattern, label and hint; error-other when none applies) and removes error-* labels that no longer apply; the green screenshot-ok label marks a passed test whose screenshot code/check-screenshot.sh found fine (no warnings). When the test failed or reports warnings or name remarks, the comment @mentions the GitHub account the AppImage comes from (code/upstream-owner.sh on the first line of the PR's data/ files, read via the API at the tested commit, not from the artifact), unless it is the PR's author or a bot, or was mentioned in an earlier test result comment already; other hosts have no GitHub account to mention. The comment says which file was tested (Tested: the file name, linked, and the release it comes from, with a remark if the release is marked as a pre-release or its tag looks like one: alpha, beta, rc; from the URL: line of the log, which the test result artifact carries as tested.txt; only URLs of a strict form are accepted). Finally it auto-merges (squash) a PR from a returning contributor (author_association CONTRIBUTOR or above) that changes exactly one file in data/, passed with screenshot-ok, has no manual-check-needed or do-not-merge label, and does not change the first line of an existing file in data/ (checked itself via the API, not via the artifact), except to shorten a long-form link to the short form of the SAME repository (code/repo-url-for-entry.sh --shortens: https://github.com/o/r/releases or .../releases/download/... to https://github.com/o/r); even a change within the same owner may be a different project that shares the file name (#8569). merge-labeled.yml applies the same rule. A merge with the workflow's token does not trigger push workflows, so it starts test.yml by workflow_dispatch with the merge commit (input commit), which writes database/ as a push would. Re-test PRs (branch retest/* in this repository, opened by /retest on a merged PR) are merged whenever their test passes, even with warnings, as long as they only modify existing files in data/ and keep each file's first line (or only change it from a link to one particular release to its repository, see /retest below). Switch off: repository variable AUTO_MERGE=false.

  3. .github/workflows/check-origin.yml (pull_request_target, from master) compares the first line of each changed file in data/ with master (code/check-origin.sh: the GitHub user or organization, the project on other forges, the owner on shared hosting, else the domain). If it points to a different owner, it posts a comment marked <!-- appimagehub-origin-check --> and sets the yellow manual-check-needed label (possible takeover of an entry); both are withdrawn when a later push undoes the change. Exception: if both are GitHub repositories and GitHub itself redirects the old repository to the new one (a rename or transfer, so the same project), check-origin.sh exits 2 and the workflow posts a neutral informational note instead — no warning, no manual-check-needed label. This does not depend on the PR's own test run, which a PR could alter. (check-origin.sh exits 1 or 2 for a changed owner; the step must read that with RC=0 ; RESULT=$(...) || RC=$?, as RESULT=$(...) ; RC=$? ends the step under bash -e before anything is reported.) The same workflow also sets manual-check-needed (with its own comment, <!-- appimagehub-name-check -->) on a PR that adds or renames to a file in data/ whose name has more than two hyphens (often a version or file name instead of the application's name); withdrawn when a later push fixes it, and the label stays while either check flags the PR.

  4. .github/workflows/ping-authors.yml (monthly schedule, a real run, and workflow_dispatch with dry_run (default true), max_issues (default 5) and full_scan) runs code/check-entry.sh over the files in data/ (10 in parallel, 10 s timeouts; it stops once max_issues new dead entries are found unless full_scan) to find entries whose AppImage is gone (repository not found, no AppImage in its releases or in a directory listing, or a direct download URL returning 404/410; timeouts and other errors are unknown and are never pinged), writes a summary, and runs code/ping-authors.sh. A dead link to a release asset (GitHub, Codeberg or GitLab) whose repository still has an AppImage (find-appimage.sh), or to a file in a directory listing when a directory up to 3 levels above it has an AppImage of the app (e.g. download.kde.org), is fixable (pointing to the repository or directory): it opens a pull request (branch ping-authors/fixes-*, at most 5 entries per run, none already in an open fix PR) that points those entries to the repository and closes open issues about them when merged; PRs opened with the workflow's token start no workflows, so close and reopen it to test. Only the rest is pinged: code/ping-authors.sh opens (at most max_issues) issues labeled entry-unavailable for dead entries that never had one (open or closed), @-mentioning the author of the commit that added the entry and the upstream GitHub owner (never probonopd or bots), each entry at most once. It never removes an entry. One run at a time (concurrency). Run it by hand from the Actions tab (dry run first); see MAINTAINER.md.

  5. .github/workflows/remove-entry.yml removes entries completely with code/remove-entry.sh (data/NAME, database/NAME/, apps/NAME.md): on a maintainer's /remove comment on a "Where did the AppImage of NAME go?" issue (the name comes from the title, never from the comment; the issue is then closed), on a maintainer's /remove comment on a pull request (it is closed and labeled opt-out; the entries it adds or changes are removed if they are in the catalog), by hand with names, and on pushes to master that delete or rename files in data/ (it removes what is left of them). Deleting only data/NAME used to leave the page on the site.

  6. .github/workflows/discover-apps.yml (workflow_dispatch only; inputs count, default 1, no upper limit, and dry_run) runs code/discover-apps.sh to find GitHub repositories that publish AppImages on their releases but are not in the catalog yet, and proposes each as a new entry in its own pull request, labeled auto-discovered, for a maintainer to review. Candidates come from the GitHub search API (most stars first), one month of repository creation dates at a time with both a topic:appimage and an appimage in:name,description,readme query, going back month after month until count apps qualify (or every month since 2012 was searched, or 5.5 h passed; rate limits are waited out). A cursor in the state file, saved after every PR and every 10 months, lets the next run continue where this one stopped. A repository is skipped when it is already in data/, is added by an open pull request, was proposed before (any pull request labeled auto-discovered, in any state: merged means it is in the catalog, closed unmerged means it was rejected, and neither is retried; all of them are read, via the issues endpoint and the Repository: line of the PR bodies), was opted out (a PR labeled black opt-out, any PR in any state, names the repository or adds a data/ file with the app's name, compared by letters and digits, so the app is not proposed from another repository either; outcome opt-out), or was checked in the last 90 days without a usable AppImage (30 days if it had fewer than 5 stars, as it may have gained some). What remains is checked (in random order) with code/fetch-releases.sh and code/find-appimage.sh (exactly one x86_64 AppImage, in a release less than 2 years old) and code/check-name.sh (STRICT=true). If the repository is a fork or a copy of another that publishes an AppImage too (the fork's source or parent, a repository with the same letters and digits in its name linked from the description, homepage or README, or one the search finds by name with more stars), that repository, the application's own, is checked and proposed instead (outcome copy for the fork or copy; skipped if the original is known already), and the PR says which repository led to it; a fork whose source publishes no AppImage gets the not-upstream label. A very high star count for a brand-new repository (more than ~15 stars per day since it was created, at least 300, under ~2 years old) can mean bought or botted stars, so the PR gets the yellow manual-check-needed label and a note (which also keeps it out of auto-merge). The name (file in data/, branch and PR title) is the proper spelling picked by code/pick-name.sh from the repository name, the AppImage's name, the description and the README's headline (same letters and digits as the repository name; most capitals win, then the headline; blanks, and dots between words as in Uploader.PRO, become _: photoapp + PhotoApp-1.2.AppImage gives PhotoApp, photo-app + "Photo App is …" gives Photo_App); an app already in data/ in any spelling is skipped. If the repository or AppImage name, the description or the README (first 50 KB) says "unofficial", "not official", "not affiliated", "repackaged" or the like with the word AppImage or AppImages within three words of it, in the same sentence (code/not-upstream-phrase.sh; "not affiliated with " alone is no reason), the PR also gets the not-upstream label and a note naming the phrase and where it was found (the repackaged label instead, if the phrase is "unofficial", "repackaged", "third party" or "community build": built by someone else from the application, as pkgforge-dev's and ivan-hc's AppImages are); every repository checked is recorded in the state file with its outcome, so it is not checked again for 90 days. The state file (discover-state.tsv, with the cursor on its first line) lives on its own orphan branch, discover-state, never on master. The pull request's branch (discover/<name>) is pushed, and the pull request opened, with DISCOVER_TOKEN or SCREENSHOT_UPLOAD_TOKEN when set (see MAINTAINER.md), so its Test workflow actually starts; otherwise GITHUB_TOKEN is used and the pull request body says to close and reopen it. publish-pr-screenshot.yml's auto-merge skips pull requests whose branch starts with discover/ or that are labeled auto-discovered: a maintainer always reviews these.

    .github/workflows/discover-pkgforge.yml (workflow_dispatch only; inputs limit (maximum number of apps to add, default 1) and dry_run) does the same for the AppImages that https://github.com/pkgforge-dev builds, with code/discover-pkgforge.sh: it reads the organization's repositories (most recently pushed first), skips archived ones, forks and those whose name does not end in -AppImage (its own tools such as sharun), and apps already in data/ (by URL or by name), added by an open PR or named by an auto-discovered/opt-out PR (any state); the rest is checked like in discover-apps.yml (find-appimage.sh: exactly one x86_64 AppImage, in a release less than 2 years old; pick-name.sh; check-name.sh). pkgforge-dev builds other projects' applications, so every PR gets auto-discovered and repackaged (not not-upstream: repackaged already says it): a maintainer decides. It keeps no state (repositories without a usable AppImage are checked again on the next run).

    .github/workflows/discover-apphub.yml (workflow_dispatch only; inputs count (default 1) and dry_run) does the same for AppImageHub (the openDesktop/Pling store) with code/discover-apphub.sh. AppImageHub's own API host is deprecated, but the shared OCS v1 API still serves it anonymously at https://api.opendesktop.org/ocs/v1/; the app categories are the ones whose xdg_type is bin. An entry's downloadlink is a tokenized, expiring Pling URL and its homepage points back to the openDesktop page — neither is stable — but for "link" entries the Pling URL simply redirects to the real upstream (e.g. digiKam → https://download.kde.org/stable/digikam/). So the script resolves each entry's download to its final URL and proposes it only when that is stable and resolvable by the existing helpers: a GitHub/GitLab/Codeberg repository (fetch-releases.sh + find-appimage.sh), a download directory ending in / (fetch-listing.sh), or a versionless "latest" .AppImage link; Pling-hosted files, versioned files and non-listing HTML are skipped. Apps already in data/, added by an open PR, or named by an auto-discovered/opt-out PR (any state) are skipped by name. Same auto-discovered label and DISCOVER_TOKEN/SCREENSHOT_UPLOAD_TOKEN/GITHUB_TOKEN handling as discover-apps.yml; a maintainer reviews the PRs.

  7. .github/workflows/auto-retest.yml (issue_comment only) re-tests a failed pull request without anyone typing /retest: on a comment (not starting with /, not by a bot) from a maintainer, the PR's author or the GitHub account the AppImage comes from (code/upstream-owner.sh on the first line of the PR's data/ files at its head commit) that says it is fixed or asks for a re-test (code/retest-comment.sh: "retest", "re-run", "is out", "new release", "fixed in", "should now work", ...; quoted lines, code and sentences about the future such as "will fix" or "in the next release" do not count), on a PR whose latest test did not pass cleanly (an error-* label, or no screenshot-ok). It closes and reopens the PR with code/retest-pr.sh (SCREENSHOT_UPLOAD_TOKEN; reopens with GITHUB_TOKEN should that fail, never leaves a PR closed; skips a PR whose Test run for its current commit started less than 15 minutes ago) and reacts 🚀. Nothing from the PR is checked out or run; it reads the PR's files as text via the API.

  8. Answers to comments, without a maintainer:

    • auto-retest.yml also answers a question about how to test again (code/retest-question.sh, e.g. "how do I ask it to retry?") once per PR with "comment /retest" (marker <!-- appimagehub-retest-howto -->).
    • .github/workflows/reopened-notice.yml (pull_request_target) tells a non-maintainer author who closes and reopens their own PR the same, once.
    • .github/workflows/opt-out-request.yml labels a PR opt-out and answers once when its author, or the GitHub account the AppImage comes from, says the application should not be in the catalog (code/optout-comment.sh: "please remove my app", "opt out"; questions, conditions and "close this PR" do not count). It never merges, closes or removes anything: a maintainer confirms with /remove.
    • .github/workflows/not-upstream-explained.yml: on a PR labeled not-upstream (a README saying "unofficial", "not affiliated", ... or a fork), when the GitHub account of the repository in the PR's single data/ file (not a fork, on GitHub) explains in a comment, in at least 15 words, that the application is its own upstream project (code/upstream-claim.sh; any sign of repackaging means no), the not-upstream label is removed and manual-check-needed is added, with one comment: a maintainer still decides. Of 549 PRs with the label (534 open), most are misdetections or own projects, and maintainers have never ruled on the label itself: all 13 labeled PRs merged were merged by hand after the tests passed.
    • .github/workflows/notify-tauri-diricon.yml (workflow_dispatch only; inputs limit (default 100) and dry_run (default true), code/notify-tauri-diricon.sh): Tauri before 2.11.4 built AppImages without .DirIcon (tauri-apps/tauri#15596). It posts one friendly message (marker <!-- appimagehub-tauri-diricon -->: use Tauri 2.11.4 or later, build a new release, comment /retest) on each open PR that has the error-missing-file label, mentions "tauri" in its title, description or comments, and whose last test result says .DirIcon is missing (the label alone also covers other missing files). Run the dry run first.
    • code/diagnose.sh has hints for AppRun.wrapped: Permission denied (Tauri/linuxdeploy mode 0770) and for a .DirIcon that cannot be read (absolute symlink).

Rules that are easy to get wrong

  • pull_request_target workflows must never check out or run code from the PR. check-origin.yml only reads the PR's files as text via the API.

  • The artifact is untrusted (it comes from a PR's test run). In the publish workflow never execute or eval anything from it; cross-check the PR number against the tested commit; only accept hints listed by code/diagnose.sh --list from master, and values of known form; put log text only inside a code fence (four backticks, longer runs are neutralized).

  • workflow_run workflows always run from master. Changes to publish-pr-screenshot.yml (and to the hint list it validates against) only take effect after merging; a PR cannot test them. workflows: takes the workflow name (Test), not its path.

  • Never let worker.sh leave background processes behind. Anything started with & inherits stdout, which is piped into tee; a survivor keeps the pipe open and the job hangs until the Actions timeout instead of failing. The cleanup EXIT trap kills them and unmounts; redirect the output of new background processes, and wrap X11 calls in timeout.

  • worker.sh runs with set -v (and partly set -x), so the log contains its own source lines and traces. Patterns in code/diagnose.sh for the worker's own messages are anchored with ^, and the excerpt drops lines that are verbatim lines of worker.sh or traces (^+).

  • The "first error" excerpt (code/diagnose.sh --excerpt) starts at a line with error while loading shared libraries wherever it is (a missing library is almost always the real cause; label error-missing-library), else at the first line matching an error pattern; patterns of hints without a label (warnings, remarks) never start it.

  • The test runs without network (firejail --net=none); many applications show "update check failed" and similar. That is why soft error words only warn.

  • Terminal applications (Terminal=true) run with --help in xterm; screenshot checks only warn for them.

  • Thresholds in code/check-screenshot.sh were calibrated on the ~1500 screenshots in database/. When changing them, re-run over those screenshots (OMP_THREAD_LIMIT=1 for tesseract, or it crawls when run in parallel) and report how many would change outcome.

  • Adding apt packages to test.yml: bump the cache version: next to the list.

Testing changes

  • Shell: bash -n, shellcheck -S warning code/*.sh, actionlint .github/workflows/*.yml.
  • code/diagnose.sh, code/check-screenshot.sh, code/check-libc.sh can be run locally on a saved log, a PNG, or an AppImage plus its extracted AppDir (unsquashfs -o <offset>, where the offset is the end of the runtime's ELF section headers).
  • code/check-origin.sh OLD_URL NEW_URL (or --origin URL) runs locally; over the history of data/ (git log --diff-filter=M -- data/), about a quarter of the URL changes move to another owner.
  • code/find-appimage.sh releases.json NAME runs on a saved repos/OWNER/REPO/releases response (GitHub's shape; code/fetch-releases.sh normalizes Codeberg and GitLab to it). When changing its rules, compare its picks with the AppImages that the data/ files with direct links point to.
  • Site: bundle install (Gemfile: github-pages), then bundle exec jekyll build on a copy with only a few apps/*.md for speed. Note: feed.json is only valid JSON if the last page in permalink order is an app (pre-existing quirk of its comma logic).
  • PRs from forks must change exactly one file in data/ and nothing else (checked first in test.yml); PRs from branches in this repository are exempt.
  • End-to-end: the Test workflow only runs when the PR touches data/**. Test in a separate throwaway PR (from a branch in this repository) that adds a throwaway change to a data/ file (e.g., a trailing newline; only the first line is read) on top of your change; check the run and the PR comment, then close it. Doing this in the real PR leaves a test-result comment there that nothing removes once the PR no longer touches data/. New PR comments from master's publish workflow appear only for PRs whose head is still the tested commit.
  • To re-test an existing contributor PR with new workflow code, close and reopen it (a re-run would reuse the old workflow files). code/retest-prs.sh does this for all open PRs that change one file in data/ and last tested green (-u: instead those without a test result label; -f: instead those whose test failed and that have no labels at all; -n to only list them). For one PR, comment /retest on it (maintainers, the PR's author, and the GitHub account the AppImage comes from, per code/upstream-owner.sh): .github/workflows/retest.yml closes and reopens it with SCREENSHOT_UPLOAD_TOKEN (a reopen with GITHUB_TOKEN starts no workflows), or without that secret re-runs its last Test run (old workflow files); it reacts 👀, then 🚀 once the test is started. On a merged PR it opens a new PR (branch retest/<PR>-<time>, with the personal token) that only toggles the trailing newline of the merged PR's files in data/ (an entry that links to one particular release, .../releases/download/v1.3.2/..., is changed to its repository URL instead, code/repo-url-for-entry.sh, so that the newest release is tested), so that Test runs for those entries again (and, if green, auto-merge takes it, which refreshes database/); one open re-test PR per merged PR. Failed PRs are also re-tested when their author says it is fixed (item 7 above), and code/retest-pr.sh [-n] NUMBER re-tests one PR by hand (needs PAT). The comment patterns: echo "v1.2 is out" | code/retest-comment.sh.
  • .github/workflows/retest-stale.yml (workflow_dispatch only; inputs limit (default 10), days (default 365) and dry_run (default true)) re-tests the entries whose database/NAME was last changed more than days days ago (code/retest-stale.sh: from the git history, oldest first, about 1200 of them in October 2026): one retest/stale-NAME-<time> pull request per entry (the Test workflow stops at the first failing entry of a PR), changing data/NAME the way /retest does on a merged PR (a link to one particular release becomes the repository URL, else the trailing newline is toggled), with SCREENSHOT_UPLOAD_TOKEN so that Test starts. A passing one is auto-merged like any re-test PR, which refreshes database/; a failing one stays open with the test result (and the upstream account is mentioned). Entries named in the title of an open PR (not their files: thousands of open PRs, 1000 API requests an hour), or that this script re-tested in the last 60 days (any state), and entries without a file in data/, are skipped.
  • /appstream (maintainers, or the author of the issue or PR): .github/workflows/appstream-help.yml posts code/appstream-help.md from master, how to ship an AppStream metainfo file with screenshots. The catalog shows the metainfo's screenshot (type="default", else the first; from *.metainfo.xml or *.appdata.xml) instead of the automated one, which the test still takes and checks.

Investigating and answering in pull requests

Only when the maintainer explicitly asks for it (e.g. "look into the complaint in PR #123 and answer"). Never comment on, close, label or merge PRs on your own initiative, and never start conversations with contributors.

Investigate before answering, and keep the context small:

  • Read the comment, the PR's data/ file and the bot's test result comment (<!-- appimagehub-test-result -->).
  • Download the job log (repos/…/actions/jobs/<id>/logs, the job of the run linked from the test result) and grep it locally instead of reading it: URL from GitHub API: (the release asset that was tested), X-AppImage-, Screenshot:, ^ERROR, ^WARNING.
  • Which release is current: https://github.com/<owner>/<repo>/releases/latest redirects to it.
  • Claims about the AppImage itself (e.g. which glibc it needs): download it, extract it with unsquashfs -o <offset> (see "Testing changes"), and find the files responsible, e.g. with objdump -T for *UND* GLIBC_ symbols. Everything inside the AppImage counts, even a rarely loaded library, as long as whatever loads it is also in the AppImage (not on the host).
  • Remember how the test runs the app: without network, --help in xterm for Terminal=true, screenshot after at least 10 s.
  • If our test or wording is wrong, fix it (in a PR as usual) and re-test the contributor's PR by closing and reopening it.

Write the answer:

  • Show the draft to the maintainer first; post only after they approve it, or hand it to them to post themselves.
  • Be very polite: thank them, apologize if the PR waited long, agree where they are right.
  • State facts with evidence: the exact version, file path, symbol or log line. No guesses; say what they can do (e.g. remove or rebuild a file), and mention further findings only as friendly suggestions.
  • Follow the attribution rules of the environment the agent runs in.

Conventions

  • Keep the shell style of the surrounding code (plain bash, [ x"$A" == x... ] in old code is fine to leave).
  • Messages meant for contributors should say what to do, in plain words.
  • Existing entries are not re-tested automatically; new checks and flags apply to PRs and to entries as they are updated.