diff --git a/MIGRATION_PLAN.md b/MIGRATION_PLAN.md new file mode 100644 index 00000000..ef57cc7e --- /dev/null +++ b/MIGRATION_PLAN.md @@ -0,0 +1,118 @@ +# Bearhub Migration Plan + +This plan translates the roadmap into concrete engineering tasks with sequencing and acceptance criteria. + +## Phase 0: Inventory and Risk Mapping + +Tasks: +- Enumerate remaining `bauh` references: + - Python imports + - resource paths + - UI strings + - desktop entries + - log prefixes +- Classify each reference as: + - user-facing + - internal-only + - compatibility-critical + +Acceptance: +- Single tracking list with owner and status for each category. + +--- + +## Phase 1: User-Facing Decoupling + +Tasks: +- Replace user-visible `bauh` names with `Bearhub`. +- Normalize status/notification/error message prefixes. +- Validate desktop launcher and tray naming. + +Acceptance: +- No user-facing `bauh` in default UI flow. +- Docs and runtime naming are aligned. + +--- + +## Phase 2: Namespace Transition Architecture + +Tasks: +- Define target namespace: `bearhub`. +- Create temporary compatibility package: + - `bauh` imports forward to `bearhub`. +- Define migration order: + 1. core modules + 2. qt/view modules + 3. gem backends + 4. tests + +Acceptance: +- Design note committed with: + - shim scope + - deprecation window + - removal criteria + +--- + +## Phase 3: Incremental Code Migration + +Tasks: +- Move modules in small batches. +- Update imports and resource path lookups per batch. +- Keep compatibility imports passing until final cut. +- Run smoke tests after each batch: + - app start + - package search + - install + - uninstall + - update + +Acceptance: +- Main application runs from `bearhub` namespace. +- Legacy imports still function during transition. + +--- + +## Phase 4: Packaging and Distribution Alignment + +Tasks: +- Update `pyproject`/entry points to final namespace. +- Validate AUR (`bearhub`, `bearhub-git`) install paths and desktop files. +- Ensure release tags and checksums reflect migrated structure. + +Acceptance: +- Stable and `-git` packages build/install successfully. +- No stale paths in PKGBUILD or runtime scripts. + +--- + +## Phase 5: Compatibility Removal + +Tasks: +- Announce shim deprecation in changelog. +- Remove `bauh` compatibility layer after deprecation window. +- Run full regression smoke test and release candidate. + +Acceptance: +- Codebase is fully `bearhub` namespace. +- No required runtime dependency on legacy `bauh` package structure. + +--- + +## Tracking Template + +Use this minimal template per task: + +- `Task`: short description +- `Owner`: maintainer +- `Status`: todo / in-progress / blocked / done +- `Risk`: low / medium / high +- `Verification`: command or scenario used to validate + +--- + +## First Technical Slice (recommended now) + +1. Add `NAMESPACE_MIGRATION.md` with exact module move order. +2. Implement compatibility shim skeleton (`bauh` -> `bearhub` forwarding). +3. Migrate one low-risk module group and validate with smoke test. diff --git a/ROADMAP.md b/ROADMAP.md new file mode 100644 index 00000000..8d2674b8 --- /dev/null +++ b/ROADMAP.md @@ -0,0 +1,85 @@ +# Bearhub Roadmap (2026) + +This roadmap defines how Bearhub becomes an independent, Arch-first project while keeping release stability. + +## Principles + +- Keep user-facing stability first. +- Prefer small, reversible changes. +- Ship frequently and document every release-impacting change. +- Keep legacy compatibility only as long as needed. + +## Milestones + +### M1: Identity Completion (2 weeks) + +Scope: +- Remove remaining `bauh` naming from UI text, notifications, tray labels, and docs. +- Ensure links (issues, docs, release checks) point to Bearhub endpoints. +- Verify desktop integration uses Bearhub naming and icon assets. + +Definition of Done: +- No user-facing `bauh` labels left in default English UI path. +- README and release notes match actual runtime behavior. +- Basic smoke test passes (start/search/install/uninstall/update). + +### M2: Runtime Stability Baseline (2-3 weeks) + +Scope: +- Fix known uninstall/Qt lifecycle crash paths. +- Add guardrails around async UI actions and thread teardown. +- Add reproducible bug templates for crash reports. + +Definition of Done: +- No known deterministic crash in core uninstall flow. +- Bug reports include enough data to reproduce (backend, package type, logs). +- `bearhub-git` receives at least one stable cycle without critical regressions. + +### M3: Namespace Migration (`bauh` -> `bearhub`) (3-5 weeks) + +Scope: +- Migrate Python package namespace from `bauh` to `bearhub`. +- Provide temporary import compatibility layer for transition period. +- Move resource paths to Bearhub namespace. + +Definition of Done: +- Main entry points import from `bearhub`. +- Compatibility shim exists and is marked for removal date. +- Packaging and tests run successfully with new namespace. + +### M4: Backend Governance (2-3 weeks) + +Scope: +- Formalize supported backends: + - Primary: Arch/AUR + - Secondary: Flatpak, AppImage, Web +- Introduce backend capability flags and cleanup dead code paths. +- Remove unmaintained backend remnants from settings and actions. + +Definition of Done: +- Supported backend matrix documented. +- Unsupported backend code is either removed or hard-disabled. +- Settings UI matches actual supported feature set. + +### M5: Release and Maintainer Independence (ongoing) + +Scope: +- Establish Bearhub release train (`stable` + `-git` cadence). +- Document release checklist and AUR sync workflow. +- Define maintainer responsibilities and review rules. + +Definition of Done: +- Repeatable release process documented. +- At least 2 maintainers can publish stable release without ad-hoc steps. +- Changelog quality and release metadata are consistent. + +## Release Cadence + +- `bearhub-git`: continuous +- `bearhub` stable: on validated milestone increments or critical fixes + +## Immediate Next Actions + +1. Complete M1 gap scan (`bauh` strings still visible in UI and logs). +2. Build M2 issue list from current crash reports and prioritize top 3. +3. Start M3 technical design (import shim + package move order).