Skip to content

Release preparation

COLEMAN keeps public product documentation centered on CI test prioritization, selection and evidence. Generic decision contracts support that product; a release should explain the value to CI users before listing internal implementation work.

Versioning and integration

The published COLEMAN 4.9 release adds larger LRTS histories with explicit stage views: frozen ActiveMQ and Log4j source profiles, analytical/native Parquet and actual checkpointed replay. Source groups and temporal blockers remain explicit. The signed wheel, source archive, SBOM and synchronized lock are available in the release assets.

The published COLEMAN 4.8 release combines bounded ZIP64 source integrity and the complete RTPTorrent Parquet/replay workflow, including the Linux worker memory-accounting correction. The verified wheel, source archive, Sigstore bundles, SBOM and synchronized lock are available in the release assets.

COLEMAN 4.7 introduced the real LRTS download-to-Parquet workflow, including analytical tables, explicit native simulation input and actual runner/checkpoint recovery. Its source-admission and confirmatory-evidence limits remain explicit.

COLEMAN 4.6 adds versioned controlled fault observations, a pinned offline JUnit3 source recipe and recoverable raw evidence. Existing native TCPCI experiments and learning checkpoints keep their contracts. Controlled source reproduction remains separate from benchmark admission.

COLEMAN 4.5 added bounded RTPTorrent and LRTS source readers, explicit units/provenance and installed native CI/checkpoint workflows. It retains the exact numeric safeguards from 4.4.1, corpus profiles and secure source cache. Both external sources remain blocked for protected temporal evaluation. The public corpus program continues in subsequent compatible 4.x feature releases; compatible corrections use patch versions. Follow the public roadmap in dependency order and keep each PR runnable and independently reviewed. Publishing a slice does not complete the remaining corpus-admission or confirmatory-evidence gates.

A release branch can collect related reviewed PRs when a capability needs several vertical slices before publication. Keep it synchronized with security fixes from main; available security corrections must not wait for a feature release. The publication workflow runs on main. A compatible feat: merge requests the next minor version; fix: requests a patch. Reserve feat!: or an explicit breaking-change declaration for an actual incompatible public contract.

Before integrating a release branch, review its entire diff and pass the full quality/security/install/native-CI gates. Do not manually edit only the package version while leaving tags or the lock inconsistent. The automated workflow updates the package version, synchronizes uv.lock, builds the distributions, and includes the lock in the version commit before tagging. A second lock check after tagging must find no changes. This keeps the tag, source archive and wheel metadata consistent.

Reviewed release descriptions

Before the final release PR, commit docs/releases/<version>.md with an en-US release description. The publication workflow uses docs/releases/<version>.md when present; otherwise it preserves the generated description. These notes are part of the reviewed diff and must describe only completed, validated public features.

Write for a new CI user:

  • the concrete problem the release solves and useful workflows;
  • the delivered capabilities and a runnable starting example;
  • compatibility, Python requirements and any migration steps;
  • correctness/security evidence and its limits;
  • known limitations and links to the full changes.

Avoid unsupported algorithm superiority, universal generalization or wall-clock savings claims. Separate modeled objectives, measured CI outcomes, mathematical correctness and protected empirical evidence. Negative and inconclusive outcomes remain results.

After automatic publication, check the rendered GitHub description, assets, checksums, attestations, SBOM, package version and source/lock consistency. If the automatic description needs an editorial correction, update it from a reviewed notes file rather than replacing it with an unverified marketing claim.