bearhub/NAMESPACE_MIGRATION.md

# Namespace Migration (`bauh` -> `bearhub`)

This document defines the technical migration strategy for moving the Python package namespace from `bauh` to `bearhub` safely.

## Current State

- Runtime implementation still lives under `bauh/`.
- Project/package identity is already `bearhub` (metadata, binaries, releases).
- Entry points still target `bauh.*` modules.

## Migration Goals

- Make `bearhub` the canonical Python namespace.
- Keep temporary compatibility for legacy `bauh` imports.
- Avoid breaking AUR/PyPI/runtime while migration is in progress.

## Phase Plan

### Phase A: Introduce target namespace skeleton (current)

- Add `bearhub/` package wrappers that delegate to `bauh/`.
- Keep behavior unchanged.
- Do not switch entry points yet.

### Phase B: Move core modules

Order:
1. `api`, `commons`, `context`
2. `view` / `qt`
3. `gems`
4. CLI + app entry modules

Rules:
- Move one group at a time.
- After each move, keep compatibility imports in `bauh`.
- Run smoke test: start, search, install, uninstall, update.

### Phase C: Flip entry points

- Change project scripts to:
  - `bearhub = bearhub.app:main`
  - `bearhub-tray = bearhub.app:tray`
  - `bearhub-cli = bearhub.cli.app:main`
- Keep compatibility layer for one deprecation window.

### Phase D: Remove legacy compatibility

- Remove `bauh` wrappers only after:
  - one stable release cycle without namespace-related regressions
  - migration completion is documented in changelog

## Compatibility Policy

- During migration, both imports should work:
  - `import bearhub`
  - `import bauh`
- `bearhub` is canonical for new code.
- `bauh` should only be used as temporary compatibility path.

## Verification Checklist

- `python -m py_compile` passes for changed modules.
- GUI starts and basic actions work.
- AUR `bearhub` and `bearhub-git` build/install successfully.
- No user-facing regression in naming/path behavior.