reporting.md
936 tokens · o200k_base · 3,935 bytes
Source excerpt starting at line 1.# Reporting a Crash Upstream to Omarchy Read this only after concluding that a crash is genuinely Omarchy's to fix. ## Is it even Omarchy's bug? Be strict here. Omarchy is a configuration layer over Arch Linux, so a crashinside a third-party application — a file manager, a browser, a GNOME or Qtlibrary — is almost always an upstream bug in **that** project, not in Omarchy. Omarchy's sphere of control is roughly: - the `omarchy-*` commands- the Quickshell shell and its plugins- the Hyprland and terminal configuration it ships- its themes- its install and migration scripts- how it packages and configures what it installs A crash in a program Omarchy merely installs is **not** an Omarchy bug unlessOmarchy's own packaging or configuration is implicated. If it is not Omarchy's, say so and stop. Suggesting the right upstream project isuseful; filing there yourself is not part of this. ## Three conditions, all required 1. **It is a verified bug in Omarchy's sphere**, established on evidence. Issues are for verified bugs only. An "is this even a bug?" belongs on the Discord at <https://omarchy.org/discord>; a feature idea belongs in GitHub Discussions under Suggestions.2. **The user has explicitly agreed.** Show them the exact title and body you propose, and wait for a yes. Never file unprompted.3. **The machine can file it** — `gh auth status` must succeed. If `gh` is missing or unauthenticated, do not install or authenticate it. Say so, and hand the user the finished text to submit themselves. ## Search before filing A duplicate issue costs a maintainer more time than no report at all. ```bashgh search issues --repo omacom/omarchy "<program> crash"gh issue list --repo omacom/omarchy --state all --search "<signal> <program>"``` Search on the crashing program, the signal, and distinctive symbols from thebacktrace — not on the wording of the title you were about to write. `gh search issues` accepts only `open` or `closed` for `--state`, and errors onanything else. Leaving it off searches both, which is what you want here. Include **closed** issues. A matching issue closed as fixed, when the crash stillreproduces on a current system, is a regression — and reporting that is worth farmore than another duplicate. ## Adding to an existing report If a plausible match comes back, read it properly first: ```bashgh issue view <number> --repo omacom/omarchy --comments``` Confirm it is genuinely the same failure. The same program crashing is not thesame bug if the trigger or the stack differs. If it is the same, add to that issue rather than opening a new one — but onlywhen you have something the thread does not already contain: a differentreproduction, a symbolized stack where it has none, a narrower trigger, a versionwhere it regressed. A comment that only says the bug happens to you too is noise. If that is all youhave, tell the user so and file nothing. ```bashgh issue comment <number> --repo omacom/omarchy --body "..."``` ## Filing a new issue Only when the search turns up nothing that matches: ```bashgh issue create --repo omacom/omarchy --title "..." --body "..."``` Include what happened, what was expected, steps to reproduce, system details from`omarchy version`, and diagnostics from `omarchy debug --no-sudo --print` (whichalso writes `/tmp/omarchy-debug.log`; the interactive `omarchy debug` can uploadit and print a shareable URL worth including). `gh` cannot attach media. If a screenshot would help, save one and give the userthe path to drag into the web form. ## Signing End the issue or comment with a line naming the model and agent harness thatproduced it, so a human reader knows it was machine-authored: > Filed by \<model name\> via \<agent harness\>. Use your actual model and harness names. If you are not certain of them, say soplainly rather than inventing a version string.