From 003f71f1a829a6f8c3f42cc9ad03eda1d4ce14d2 Mon Sep 17 00:00:00 2001 From: Sebastian Palencsar Date: Sat, 27 Jun 2026 11:00:08 +0200 Subject: [PATCH] docs: add known-issues.md for recurring pitfalls and bugs Living maintainer/agent reference for AUR/yay cache failures, GitHub vs AUR workflow, CI import errors, release tag gaps, and M1/M2 open areas. --- CHANGELOG.md | 1 + NAMESPACE_MIGRATION.md | 1 + README.md | 1 + docs/known-issues.md | 167 +++++++++++++++++++++++++++++++++++++++++ 4 files changed, 170 insertions(+) create mode 100644 docs/known-issues.md diff --git a/CHANGELOG.md b/CHANGELOG.md index 45c1adf5..55c75534 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -47,6 +47,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). - `docs/qt6-migration.md`, `ROADMAP.md` M6, and `NAMESPACE_MIGRATION.md` history sections updated to `bearhub/*` paths - `packaging/aur/README.md` — AUR workflow (GitHub vs AUR separation), current `pkgrel=11` - `ROADMAP.md`, `README.md` maintainer sections updated for post-migration state +- `docs/known-issues.md` added — living doc for recurring issues (AUR, CI, release gaps) ### Compatibility - `bauh/api/*`, `bauh/commons/*`, `bauh/gems/*`, `bauh/view/*` remain installable as thin re-export shims (`from bearhub. import *`) diff --git a/NAMESPACE_MIGRATION.md b/NAMESPACE_MIGRATION.md index f33bacb8..60739cea 100644 --- a/NAMESPACE_MIGRATION.md +++ b/NAMESPACE_MIGRATION.md @@ -382,4 +382,5 @@ Run after every migration slice: - `docs/qt6-migration.md` — Qt6 inventory under `bearhub/view/qt/*` and `bearhub/view/core/*` - `CHANGELOG.md` — `[Unreleased]` on `main` (Phase B + partial Phase D); tagged `0.10.7-bearhub.4` … `.6` - `packaging/aur/README.md` — AUR publish workflow (GitHub ≠ AUR) +- `docs/known-issues.md` — recurring bugs and maintainer pitfalls (update when learning new ones) - `AGENTS.md` — **local** AI/maintainer handoff (gitignored, not on GitHub) \ No newline at end of file diff --git a/README.md b/README.md index 11d7eb87..b3491065 100644 --- a/README.md +++ b/README.md @@ -208,6 +208,7 @@ Bearhub is currently distributed through source releases and AUR: - Qt6 plan: `docs/qt6-migration.md` - AUR templates + publish workflow: `packaging/aur/README.md` (**GitHub push ≠ AUR**; local AUR clone + SSH push) - AUR stable (2026-06-27): `bearhub 0.10.7-11` — source still tag `0.10.7-bearhub.6` until next release +- Known issues / pitfalls: `docs/known-issues.md` (AUR, CI, release gaps — **keep updated**) - Local agent handoff: `AGENTS.md` (gitignored, maintainer machine only) - Brand assets: `gfx/bearhub.svg`, `gfx/bearhub.png` → `bearhub/view/resources/img/logo.svg` - AppImage build (`linux_dist/appimage/`): diff --git a/docs/known-issues.md b/docs/known-issues.md new file mode 100644 index 00000000..93b74f60 --- /dev/null +++ b/docs/known-issues.md @@ -0,0 +1,167 @@ +# 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 \ No newline at end of file