bearhub/MIGRATION_PLAN.md

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.