docs: add the 1.0 migration guide (#287)

[Mattsface]

Closes #287

Why

Version 1.0.0 changes the default HTTP behavior so Mlb() is equivalent to Mlb(strict_http=True). Users upgrading from 0.9.x need exact guidance about what now raises, what remains compatible, and how to temporarily retain the historical behavior.

Breaking change documented

• Mlb() / MlbDataAdapter() now default to strict HTTP handling
• Final non-404 4xx responses raise MlbHttpError by default
• strict_http=False remains an explicit temporary compatibility opt-out
• Compatibility mode is no longer described as the default in current-version prose

README changes

• Added an Upgrading to version 1.0 section near the HTTP material
• Included recommended 1.0 exception-handling and temporary strict_http=False examples
• Updated the HTTP behavior table columns to Default 1.0 behavior / Explicit compatibility mode
• Replaced stale links to the 0.9.0 release notes with docs/releases/1.0.0.md
• Added a link to docs/public-api.md (file lands with Audit and define the stable public API for 1.0 #286)
• User-Agent concrete example remains python-mlb-statsapi/0.9.0 because package metadata on this branch is still 0.9.0 (offline docs consistency test)

Transport-guide changes

• Updated introduction for the 0.8 → 0.9 → 1.0 progression
• Documented default HTTP behavior and defined “final” as post-retry-exhaustion
• Replaced the mode table so default 1.0 is the first behavior column
• Documented compatibility-mode warning semantics from merged Preserve explicit compatibility mode in 1.0 #285 (status, URL, explicit strict_http=False, historical empty result, 1.0 default, how to raise)
• Added warning-as-error guidance and temporary targeted ignore guidance
• Added Migrating from 0.9.x to 1.0 with before/after examples and 404 distinction
• Preserved Session ownership, retry, timeout, User-Agent, and injected-Session documentation

Migration steps

Documented the recommended process: find empty-result 4xx reliance → handle MlbHttpError → distinguish 404 domain results → temporary strict_http=False only where needed → test warning-as-error configs → remove the opt-out → confirm Session/retry behavior.

Warning-as-error guidance

Documented promoting MlbHttpCompatibilityWarning to an error, preferred migration via removing strict_http=False, and that ignoring the warning or disabling all warnings is temporary / not recommended.

404 distinction

Documented that endpoint-specific 404 None / [] / {} behavior is preserved under both the default and compatibility mode, and that a missing person may still return None without raising.

Compatibility-mode positioning

Described strict_http=False as a temporary migration opt-out and explicit request for historical 0.9 behavior, not the recommended long-term 1.0 configuration.

Public API contract integration

Links to docs/public-api.md are present, but #286 has not merged yet, so that file does not exist on release/1.0.0. Stability wording will be reconciled against the final #286 classification after rebase. This PR remains draft until #286 is integrated. #285 is already merged.

Release-note structure

Created docs/releases/1.0.0.md with breaking change, highlights, migration guidance, documentation links, and not-included exclusions. Does not claim PyPI publication, tagging, or GitHub release.

Historical release notes preserved

docs/releases/0.8.0.md and docs/releases/0.9.0.md were not rewritten.

Dependencies integrated

Issue	Status
#284 Make strict HTTP behavior the default	Merged (8d3b7c8, verified as ancestor of release/1.0.0)
#285 Preserve explicit compatibility mode	Merged (40babef / PR #292)
#286 Audit and define the stable public API	Open / unmet — docs/public-api.md missing

Focused validation results

• Stale-phrase search in current-version docs: clean
• git diff --check: clean
• poetry check: exit 0 (existing Poetry deprecation warnings only)

Full offline-suite results

poetry run pytest tests/ --ignore=tests/external_tests -v
433 passed, 29 warnings

Build result

poetry build
Built python_mlb_statsapi-0.9.0.tar.gz
Built python_mlb_statsapi-0.9.0-py3-none-any.whl

Release-validator result

Exact blocker (unrelated pending release work; validator not changed in this issue):

AssertionError
inspect.signature(Mlb.__init__).parameters["strict_http"].default is False

The smoke test embedded in scripts/validate_release.py still asserts the 0.9 default. Package metadata on the branch is still 0.9.0. Updating the validator belongs to the release-prep / validator issue, not #287.

Link validation

docs/http-transport.md     OK
docs/releases/1.0.0.md     OK
docs/public-api.md         MISSING (#286 unmet)

Remaining blockers

1. Audit and define the stable public API for 1.0 #286 must merge and this branch must be rebased onto the final release/1.0.0
2. Public API stability wording and docs/public-api.md link validation must be confirmed against the final Audit and define the stable public API for 1.0 #286 classification
3. Release validator still expects strict_http default False and version 0.9.0 — pending separate release work

Risk assessment

Documentation-only change. No runtime behavior, constructor defaults, warnings, exceptions, retries, Session ownership, endpoint models, package exports, CI, or version metadata were modified.

  

[Mattsface]

Looks good. The docs check out.