libraries-ship-publishing-and-compatibility

name	libraries-ship-publishing-and-compatibility
description	Use when packaging, publishing, versioning, deprecating, or changing compatibility for a reusable library; extends core release rules with package formats, public API compatibility, support matrices, and consumer verification.

Library Publishing and Compatibility

Apply core-ship-release-pipeline and core-ship-versioning-and-change-communication first. Libraries require stricter compatibility because consumers deploy on their own schedules.

Define the compatibility surface

Version exported symbols and types, import paths, runtime behavior, errors, defaults, side effects, serialization, peer requirements, supported runtimes, and documented extension points. A type-only break can still be a breaking change. Fixing behavior that consumers may rely on requires explicit risk assessment under Hyrum's Law.

Publish a support matrix and test its minimum and current versions. Keep peer ranges as broad as verified and direct dependencies as narrow as ownership allows. Drop a platform only with a major release or the project's documented compatibility policy.

Package deliberately

• Export only supported entry points through the ecosystem's package metadata. Prevent accidental deep imports where tooling allows it.
• Provide only module formats the supported toolchains need, with matching types and source maps.
• Verify tree-shaking or side-effect declarations with a consumer build when claimed.
• Inspect the packed artifact before publication for missing files, unexpected size, credentials, development fixtures, and broken paths.

Release safely

Build from a clean tagged revision, run tests against the packed artifact in representative consumer projects, attach provenance/checksums when supported, and use a prerelease channel for uncertain changes. Never overwrite an existing published version.

Deprecate with a reason, replacement, migration example, and planned removal boundary. For a breaking release, provide a migration guide and codemod when mechanical changes are substantial. Keep the previous supported line available long enough for the stated policy.

Completion gate

The packed artifact, public exports, types, install path, consumer examples, support matrix, size, provenance, changelog, and compatibility classification must be verified before publication.