Release Notes: v1.0.0 - Stability Milestone and Migration Guidance

---

Summary

Version 1.0.0 formalizes the stable public architecture introduced across the 0.x series.

This release note focuses on migration expectations for users still importing from root-level compatibility shims.

Compatibility Shim Policy for 1.0.0

Root-level compatibility exports in pophealth_observatory remain available in 1.0.0, but they are deprecated.

• Removal is deferred by one major milestone and will occur no earlier than 2.0.0.
• Firm target date for removal planning: 2027-06-30.
• Runtime warnings continue to provide replacement import statements.

Recommended Import Migration

Prefer direct submodule imports instead of root-level shim imports.

Before (deprecated)

from pophealth_observatory import NHANESExplorer
from pophealth_observatory import BRFSSExplorer

After (recommended)

from pophealth_observatory.observatory import NHANESExplorer
from pophealth_observatory.brfss import BRFSSExplorer

Function Import Migration

from pophealth_observatory.laboratory_pesticides import (
    get_pesticide_metabolites,
    get_pesticide_panel,
    load_pesticide_reference,
)

Upgrade Checklist

• Replace root-level imports with submodule imports.
• Run test suite with warnings enabled in your environment.
• Verify no DeprecationWarning from pophealth_observatory root shims remains in your CI logs.

Tag-Time Release Verification

At release tag time (v*), CI enforces:

• Full repository tests (pytest -q)
• Strict docs verification (mkdocs build --strict)

Publishing proceeds only if these checks pass.

---

For policy details, see docs/versioning.md.