# mgf-common v0.33.0 — AP-12 deprecation removals

> **Audience:** consumers pinning `mgf-common` who still call the
> three deprecated names: `mgf.common.configure`,
> `mgf.common.config.make_settings_config`, and
> `mgf.common.exceptions.EnvironmentError`.

This is a **breaking minor** in the 0.x window (rule AP-03). Each of
the three removals had at least one preceding MINOR cycle emitting
`MgfDeprecationWarning` per rule AP-12. If your project ran clean
under v0.32.x with `filterwarnings = error`, you have nothing to do.

---

## What was removed

| Symbol | Replacement | Codemod? |
|---|---|---|
| `mgf.common.configure(app_name, app_version)` | `mgf.common.bootstrap(app_name=..., app_version=...)` | No — case-by-case |
| `mgf.common.config.make_settings_config(...)` | `mgf.common.config.settings_config(...)` | Yes |
| `mgf.common.exceptions.EnvironmentError` | `mgf.common.exceptions.HostEnvironmentError` | Yes |

---

## Quickest path — `mgf-fed migrate`

For the two mechanical renames, the codemod ships in `mgf-common
migrate`. Pin v0.33.0 (or any version that still bundles the codemod)
and run from the project root:

```bash
mgf-fed migrate
```

Identifier-anchored, import-gated rules apply both renames safely:

- `EnvironmentError` is renamed **only** when `mgf.common.exceptions`
  is imported in the file. Files using Python's built-in
  `EnvironmentError` (= `OSError`) are untouched.
- `make_settings_config` is renamed wherever it appears (no
  ambiguity — the name is mgf-specific).

Dry-run preview:

```bash
mgf-fed migrate --dry-run
```

---

## Manual: `configure()` → `bootstrap()`

The bootstrap reshape is **not** codemodded — it benefits from human
review per case. The common shapes:

### Before (v0.32.x and earlier)

```python
import mgf.common
from mgf.common.observability import setup_logging, setup_otel

mgf.common.configure(app_name="myapp", app_version="1.0.0")
setup_logging(level="INFO", fmt="json")
setup_otel()
```

### After (v0.33.0+)

```python
import mgf.common
from mgf.common.settings import LoggingSettings, MgfSettings

with mgf.common.bootstrap(
    app_name="myapp",
    app_version="1.0.0",
    settings=MgfSettings(
        logging=LoggingSettings(level="INFO", format="json"),
    ),
):
    # your app code here
    ...
```

`bootstrap()` wires identity + logging + OTel + excepthooks
transactionally — on any wiring failure, the LIFO rollback unwinds
partial state and raises a typed `BootstrapError`.

### Test-friendly shape

For tests that need only identity isolation (without the full wiring
stack), use the private `_set_identity()` helper:

```python
from mgf.common import _identity
_identity._set_identity("test-app", "0.0.0")
```

For tests that exercise the full stack, use `bootstrap_for_test()`:

```python
from mgf.common._test_helpers import bootstrap_for_test

with bootstrap_for_test() as ctx:
    do_work_under_test()
```

---

## Why these were removed

- **`configure`** carried a v0.1-era split (identity-only) that the
  v0.4 transactional bootstrap eliminated. Keeping both meant
  consumers had to reason about two startup shapes; the deprecation
  cycle ran from v0.4.0 → v0.32.x.
- **`make_settings_config`** was a verbose alias; `settings_config`
  is the canonical name (matches `model_config`).
- **`EnvironmentError`** deliberately shadowed Python's built-in
  alias for `OSError` — confusing in `except` clauses and in IDE
  tooltips. `HostEnvironmentError` is unambiguous.

---

## See also

- [`CHANGELOG.md`](../../CHANGELOG.md#0330--2026-05-11) — full
  release notes.
- [`PUBLIC_API.md`](../../PUBLIC_API.md) — the post-removal public
  surface.
- [`docs/standards/API_DESIGN.md`](../standards/API_DESIGN.md) — the
  AP-12 deprecation-cycle rule that governed this release.
