bearhub/docs/known-issues.md

# Known Issues and Maintainer Pitfalls

Living document for recurring problems, gaps, and non-obvious workflow traps.  
Update this file when you hit a new issue that cost debugging time.

Last updated: 2026-06-27.

## How to use this file

When you discover or fix a recurring problem, add an entry with:

- **Symptom** — what users/maintainers see
- **Cause** — why it happens
- **Fix** — concrete steps
- **Prevent** — what to do next time (docs, CI, packaging)

AI agents: read this **after** `AGENTS.md` (local) and before invasive changes.

---

## Release and packaging gaps

### `main` ahead of latest GitHub tag

| | |
|---|---|
| **Symptom** | Code on `main` has M3 migration; `pip install` from tag or AUR stable behaves differently than `main`. |
| **Cause** | Latest tag is `0.10.7-bearhub.6`; `[Unreleased]` on `main` is not tagged yet. |
| **Fix** | Tag `0.10.7-bearhub.7` (or `0.10.8`), update `packaging/aur/bearhub/PKGBUILD` source URL + `sha256sums`, publish to AUR. |
| **Prevent** | Ship release checklist in `packaging/aur/README.md` after every milestone on `main`. |

### AUR stable builds old tarball

| | |
|---|---|
| **Symptom** | `yay -S bearhub` installs code without latest `main` changes. |
| **Cause** | AUR `bearhub` uses a **tagged** tarball (`0.10.7-bearhub.6`), not `main`. Only `bearhub-git` tracks `main`. |
| **Fix** | Use `bearhub-git` for bleeding edge, or cut a new release tag + PKGBUILD update. |
| **Prevent** | Document in README maintainer section (done). |

### GitHub push does not update AUR

| | |
|---|---|
| **Symptom** | PKGBUILD changed on GitHub; `yay -Ss bearhub` unchanged. |
| **Cause** | AUR is a **separate git repo** (`aur.archlinux.org`). |
| **Fix** | Copy `packaging/aur/*` → local AUR clone → `git push` to AUR (local sync script on maintainer machine). |
| **Prevent** | Never assume `git push origin main` publishes packaging. See `packaging/aur/README.md`. |

---

## AUR / yay / makepkg

### SHA256 failed: `bearhub-0.10.7.tar.gz`

| | |
|---|---|
| **Symptom** | `makepkg` / `yay`: `bearhub-0.10.7.tar.gz ... FEHLGESCHLAGEN` |
| **Cause** | Stale cache file with generic name; old `pkgrel` used `bearhub-0.10.7.tar.gz` instead of tag-specific archive. |
| **Fix** | `rm -rf ~/.cache/yay/bearhub`; `yay -Sy`; ensure PKGBUILD uses `bearhub-0.10.7-bearhub.6.tar.gz`. |
| **Prevent** | Always use tag in source filename; bump `pkgrel` when forcing cache refresh. |

### yay shows old `pkgrel` (e.g. `-9` or `-10` while AUR git has `-11`)

| | |
|---|---|
| **Symptom** | `yay -Ss bearhub` lags behind AUR git. |
| **Cause** | Local package DB or yay clone not refreshed; AUR RPC index can trail git briefly. |
| **Fix** | `yay -Sy`; `rm -rf ~/.cache/yay/bearhub`; retry. |
| **Prevent** | After AUR push, wait a few minutes or bump `pkgrel` again if index stuck. |

### AUR SSH: `Permission denied (publickey)`

| | |
|---|---|
| **Symptom** | `git push` to `aur.archlinux.org` fails. |
| **Cause** | Missing key, or `~/.ssh/aur` permissions too open (`0644`). |
| **Fix** | `chmod 600 ~/.ssh/aur`; key registered at https://aur.archlinux.org |
| **Prevent** | `ssh -T aur@aur.archlinux.org` after setup. |

---

## CI and tests

### CI: `ModuleNotFoundError: No module named 'bauh.api'`

| | |
|---|---|
| **Symptom** | GitHub Actions unittest import errors for `bauh.*`. |
| **Cause** | Tests import `bauh.*` but shims missing (partial migration commit) or `pip install -e .` not run. |
| **Fix** | Ensure `bauh/` shims exist; tests use `bearhub.*` for primary imports; CI must `pip install -e .`. |
| **Prevent** | Run full test suite locally before push; 159 tests should pass. |

### Tests pass locally but fail in clean venv

| | |
|---|---|
| **Symptom** | Different results with/without editable install. |
| **Cause** | Running tests without `pip install -e .` — packages not on `PYTHONPATH`. |
| **Fix** | `pip install -e .` then `python -m unittest discover -s tests -p "test_*.py" -v` |
| **Prevent** | Match CI workflow in `.github/workflows/tests.yml`. |

---

## Product / UX (not bugs — known gaps)

### UI still looks like bauh

| | |
|---|---|
| **Symptom** | Bearhub visually identical to upstream. |
| **Cause** | M1 (identity) not done; same PyQt5 themes/layout; `bauh-files` assets/URLs. |
| **Fix** | M1 milestone: branding, screenshots, tray strings, data mirrors. |
| **Prevent** | Do not confuse M3 namespace completion with visual rebrand. |

### Runtime still uses `bauh-files` URLs

| | |
|---|---|
| **Symptom** | Logs/downloads reference `github.com/vinifmor/bauh-files`. |
| **Cause** | Intentional until Bearhub hosts its own datasets (see `0.10.7-bearhub.6` changelog). |
| **Fix** | Future: `bearhub-files` repo or mirrored assets. |
| **Prevent** | Document in M1/M4 before changing URLs. |

---

## Namespace migration (M3)

### Accidental edit under `bauh/` instead of `bearhub/`

| | |
|---|---|
| **Symptom** | Fix works via `import bauh` but `bearhub` path stale. |
| **Cause** | `bauh/` is shim-only; implementation belongs in `bearhub/`. |
| **Fix** | Move logic to `bearhub/`; keep `bauh/` as `from bearhub... import *`. |
| **Prevent** | Grep `bearhub/` for changes; read `NAMESPACE_MIGRATION.md`. |

### Phase D shim removal too early

| | |
|---|---|
| **Symptom** | Breaks users/scripts still using `import bauh`. |
| **Cause** | Removing `bauh/*` before one stable release on shims. |
| **Fix** | Restore shims; wait for tagged stable + AUR cycle. |
| **Prevent** | Follow Phase D checklist in `NAMESPACE_MIGRATION.md`. |

---

## Open runtime issues (M2 — investigate, not fully documented)

| Area | Notes |
|------|--------|
| Uninstall flow | Qt lifecycle / thread teardown crashes reported historically |
| Wayland | Desktop files may force `QT_QPA_PLATFORM=xcb` |
| AppImage + AppImageLauncher | Install crashes possible; documented in README |

Add concrete repro steps here when confirmed on current `main`.

---

## Related docs

- `AGENTS.md` — local AI handoff (gitignored)
- `packaging/aur/README.md` — AUR publish workflow
- `NAMESPACE_MIGRATION.md` — namespace state
- `ROADMAP.md` — M1–M6 milestones
- `CHANGELOG.md` — fixed issues per release