Document the 1.0 breaking change and migration path

[Mattsface]

Document the 1.0 breaking change and migration path

Parent release issue: #282

Depends on:

• Make strict HTTP behavior the default in 1.0 #284
• Preserve explicit compatibility mode in 1.0 #285
• Audit and define the stable public API for 1.0 #286

Why

Version 1.0.0 changes the default HTTP behavior. Users upgrading from 0.9.x need exact guidance about what now raises, what remains compatible, and how to temporarily retain the historical behavior.

Scope

Update:

README.md
docs/http-transport.md
docs/releases/1.0.0.md

Add a focused migration section for users upgrading from 0.9.x.

Required documentation

Document:

• Mlb() is strict by default in 1.0
• Final non-404 4xx responses now raise MlbHttpError
• Endpoint-specific 404 behavior remains unchanged
• Final 5xx, timeout, transport, and decode behavior
• How to use strict_http=False temporarily
• Compatibility warning behavior in explicit compatibility mode
• The supported public API and stability promise
• Session ownership and injected Session guarantees
• Retry behavior and public retry-policy usage
• The recommended migration process

Required migration example

import mlbstatsapi

# Temporary compatibility opt-out while migrating.
with mlbstatsapi.Mlb(strict_http=False) as mlb:
    player = mlb.get_person(664034)

Recommended final state:

import mlbstatsapi

try:
    with mlbstatsapi.Mlb() as mlb:
        player = mlb.get_person(664034)
except mlbstatsapi.MlbHttpError as exc:
    print(exc.status_code)
    print(exc.url)

Acceptance criteria

• The breaking change is prominent in the README and release notes
• Examples use only supported public APIs
• Documentation clearly separates 404 domain results from other HTTP errors
• strict_http=False is presented as a migration tool, not the preferred 1.0 default
• Warning-as-error environments are addressed
• Public API stability commitments match Audit and define the stable public API for 1.0 #286
• Release notes follow the established 0.8.0 and 0.9.0 structure
• Documentation matches the final implementation and validator behavior

Suggested branch

docs/v1-migration-guide

Start from and target:

release/1.0.0