浏览文档

Issues and labels

Every new issue starts from a form: app problem, app request, proposal, question about the rules, website or docs, security problem, or something else. Only the app problem form asks for much: it can’t be found without the reporter’s setup. The others take a sentence or a link, and a maintainer or an agent fills in the rest.

Labels say what an issue is about and what it is waiting for. The forms add the first one; the rest are added while it is handled.

For agents

Labels

What it is about (one per issue, set by the form or when sorting):

Label For
bug An app or install that doesn’t work
app-request An app, or a set of apps, someone would like listed
app-discover A candidate from a scan (finding apps)
proposal A change to the rules, the process, or how FlatPark works
rule-question How a rule applies, or whether an app can be listed
site flatpark.org and these docs
security A package, release or pipeline that puts users at risk
enhancement A change to an existing package that isn’t a bug: a permission, an architecture, a setting
community Growing the project: maintainers, channels, outreach
ci-alert Opened by a failing workflow; never added by hand

What it is waiting for (add and remove as the issue moves):

Label Means Remove when
needs-info The reporter has to add something: an output, a step, which app They answer
needs-testers Needs hardware or a setup we don’t have (a GPU vendor, aarch64, a desktop) Someone has tested
report-to-upstream The cause is in the app itself, not the package Never; link the developer’s issue in a comment once it is filed
help wanted Open for anyone to pick up Someone takes it (/claim removes it)

needs-testers on a PR also publishes it (check it first, as in opening a test build): once pr-checks passes, the PR gets a test repository at https://test.flatpark.org/pr/<N>/ and a comment with the install commands (testing a PR build), updated on every push. Removing the label, or closing the PR, withdraws it: installed copies show an end-of-life notice with the commands to switch back, and the files are deleted 14 days later. Adding the label again publishes it again.

help wanted says only that anyone may take it; the label beside it says what kind of help: app-request + help wanted is an app anyone may package, community + help wanted is a call for people.

Claims

Commenting /claim on an open app-request or app-discover issue assigns it to the commenter, so two people don’t package the same app; /unclaim gives it back. The comment must start with the command on its own line. A bot reacts 👍 when it worked; if someone else already holds the claim it replies with their name and assigns nobody. One claim per issue.

When an issue first gets either label, a bot comments once: it thanks the requester (app requests only) and explains /claim, so whoever reads the issue later knows to claim before starting.

A claim that has gone quiet (no PR, no answer when asked) is released by a maintainer: unassign the person, say why in a comment, and add help wanted back. Maintainers can still assign by hand; the command is for everyone else.

Closing: duplicate with a link to the earlier issue; GitHub’s “not planned” for an app that can’t be listed or a proposal that was declined, with the reason in the last comment. wontfix and invalid aren’t used.

Titles

Every issue title starts with the prefix of its “what it is about” label, however the issue was opened: from a form, by a maintainer or an agent directly, or by a bot.

Label Title
bug [Bug] <app-id>: <what goes wrong>
app-request [App Request] <Name>
app-discover [App Discover] <Name>
proposal [Proposal] <what changes>
rule-question [Question] <the question>
site [Site] <page or area>: <what>
security [Security] <app-id or area>: <what>
enhancement [Enhancement] <app-id>: <what changes>
community [Community] <what>
ci-alert [CI] <workflow>: <what failed> (set by scripts/ci-alert.sh)

The forms prefill the prefix, except “Something else”, which gets one when it is sorted. When you open an issue yourself, pick the label first and take its prefix; status labels (help wanted, needs-testers, …) never give one.

Fix the prefix and the app’s spelling (its official name, its id) when sorting; leave the rest of the reporter’s words, and never edit their text.

Sorting a new issue

  • App problem. Check the form is complete: the rpak doctor output and the output of flatpak run. If one is missing or cut short, ask for exactly what is missing and add needs-info. Go through the rpak doctor output with the list below first. Reproduce before changing the package (testing playbook); a cause in the app itself gets report-to-upstream, and a fix to the package gets a row in the incident list.
  • App request. Answer it as in finding apps.
  • Proposal, question. Answer from the docs, linking the rule. A question the docs don’t answer means the docs are missing something: say so, and fix the page in the PR that settles it.
  • Security problem. Before anything else, as security describes.
  • Something else. Give it the label it should have had, and fix the title.

Reading rpak doctor output

rpak doctor only collects; deciding what matters is done here, so this list can grow without a new rpak release. Check, in this order:

Look at What it can explain
App section: extra-data lines HTTP 404, or a size that differs from pinned: the vendor replaced or removed the file; the install or update fails with “Wrong size”. Both commits are listed when an update is pending; a broken remote commit with a good installed one fails only on update.
Network A remote that doesn’t answer, or a proxy in the way: installs and updates fail before any app runs.
global override blocks Apply to every app. A filesystem, socket or variable there explains permissions the package doesn’t grant, and settings that vanish (override).
The app’s override and permissions What the app really runs with. Compare with the package’s finish-args; a removed folder means lost settings, extra host or home grants mean the test setup differs from ours.
GPUs, NVIDIA driver, GL extension lines Two GPUs (Intel or AMD next to NVIDIA) and the nvidia driver are the setup WebKitGTK and Chromium apps most often fail on. The GL.nvidia-<version> extension must match the driver version exactly (dots become dashes), or GL falls back to software or fails.
XDG_SESSION_TYPE, XDG_CURRENT_DESKTOP, portal lines Wayland or X11, and which portal backends run: tray icons, file choosers, screenshots and “open with” depend on them. xdg-desktop-portal: not running breaks all of those.
user.max_user_namespaces=0, unprivileged_userns_clone=0 Flatpak can’t start any app.
end-of-life on the app’s runtime The app needs a runtime bump; EOL refs the app doesn’t use are unrelated.
Installations Where the app is installed (user or system), whether the remote it came from is configured there, a lock held by another process, little free space.
RPAK_DRY_RUN, RPAK_FLATPAK rpak set to do nothing, or pointed at itself.

flatpak run printing nothing doesn’t mean nothing happened: many apps (Tauri ones among them) write their log only to a file, usually under ~/.var/app/<id>/data/ or ~/.var/app/<id>/.local/share/. Find it in the app’s source or in the package’s wrapper, and ask for it by its exact path.

Write down what led to the cause in the reply, so the reporter learns to read it too. A pattern that turns up in several reports belongs in this table.

在 GitHub 上编辑此页