Automate release preparation and validation #345

Summary

Create a release helper script that automates the repetitive preparation and validation steps required for a new python-mlb-statsapi release.

The current process requires manually updating the package version, release notes, documentation references, release-validation fixtures, and then running a series of validation commands. This is error-prone and easy to partially complete.

Goal

Provide a single, reviewable release-preparation workflow that updates the expected versioned files consistently and verifies that the repository is ready to tag and publish.

Proposed scope

Add a script, for example:

scripts/prepare_release.py

The script should accept a target version such as:

python scripts/prepare_release.py 1.1.2

and automate or validate the following:

• update pyproject.toml to the target version
• create or initialize docs/releases/<version>.md
• add the release to docs/releases.md
• add the release notes page to mkdocs.yml
• update current-version references in README.md
• update current-version references in docs/http-transport.md
• update CURRENT_RELEASE_NOTES in tests/test_release_validation.py
• move the previous current release into HISTORICAL_RELEASE_NOTES
• fail cleanly if the requested version already exists or repository state is inconsistent
• print a clear summary of files changed and remaining manual release steps

Validation

The workflow should make it easy to run the full pre-release checks afterward, ideally through either this script or a companion command:

poetry run pytest tests/ --ignore=tests/external_tests
poetry run pytest tests/external_tests/
poetry build
python scripts/validate_release.py
poetry run twine check dist/*

Consider adding a --check / dry-run mode that verifies release readiness without modifying files.

Non-goals

The initial version should not automatically:

• create or push git tags
• publish to PyPI
• create a GitHub Release
• push commits or branches

Those operations should remain explicit/manual until the preparation script is proven reliable.

Acceptance criteria

• One command updates all version-specific release-preparation files consistently
• The script refuses invalid or duplicate versions
• The script is idempotent or fails safely on a partially prepared release
• A dry-run/check mode is available
• Unit tests cover version parsing and file-update behavior
• Existing release-validation tests continue to pass
• Documentation describes the release workflow