Public API Compatibility

Buffalo Core is a small foundational package, so compatibility decisions have outsized effects on downstream projects. This document defines what should be treated as public API and how compatibility changes should be communicated.

Public API Surface

The supported public API consists of:

  • the re-exported names in buffalo_core

  • the documented public objects in buffalo_core.typing

  • the documented public objects in buffalo_core.numeric

  • the documented public objects in buffalo_core.diagnostics

Anything else should be treated as internal unless it is explicitly documented as public.

Compatibility Expectations

The following changes should be treated as breaking changes:

  • removing or renaming a public export

  • moving a public object without keeping a compatibility import path

  • changing the normalized dtype returned by as_float_array or as_int_array

  • changing the scalar coercion behavior of as_float_scalar or as_int_scalar

  • changing the fields, field meanings, or constructor expectations of public diagnostics dataclasses

  • changing the semantic meaning of DiagnosticSeverity, DiagnosticReport, or OperationResult

The following changes are usually non-breaking:

  • adding new public helpers or aliases

  • improving docstrings or examples

  • internal refactors that preserve the documented behavior

  • tightening validation for clearly invalid inputs when the old behavior was inconsistent or incorrect

Versioning Policy

Buffalo Core is still pre-1.0. That means change is expected, but public changes should still be deliberate and clearly documented.

Use this release guidance:

  • Patch releases should preserve the public contract and focus on bug fixes, documentation, and internal maintenance.

  • Minor releases may add public API.

  • Any intentional breaking change should be called out explicitly in release notes and downstream project update notes.

If a public change will require updates in Buffalo Wings, Buffalo Panel, or other Buffalo projects, document that impact before release.

Compatibility Review Checklist

Before merging a public API change, check all of the following:

  1. Is the affected name or behavior documented in the API reference, examples, or design docs?

  2. Will any downstream Buffalo project need an import-path change, behavior change, or test update?

  3. Does the Towncrier fragment describe the downstream effect clearly enough for release notes?

  4. If the change is breaking, is the release plan and follow-up work explicit?