dataexcept 0.1.0-beta.2

Structured errors and failure observability for data, ML, and data-engineering systems
Documentation
# Releasing

## crates.io Trusted Publishing

The crate uses crates.io Trusted Publishing through GitHub Actions.

Configure the trusted publisher on crates.io with:

- **GitHub owner:** `DiogoRibeiro7`
- **Repository:** `dataexcept-rs`
- **Workflow:** `release.yml`
- **Environment:** leave empty

The workflow lives at `.github/workflows/release.yml` and requests
`id-token: write`. Authentication is performed with
`rust-lang/crates-io-auth-action@v1`, which provides a short-lived crates.io
token to `cargo publish`.

No long-lived `CARGO_REGISTRY_TOKEN` GitHub secret is required for normal
releases after Trusted Publishing is configured.

## Publish a release

1. Prepare and merge the version/changelog PR into `main`.
2. Open **Actions → Release → Run workflow**.
3. Enter the exact crate version from `Cargo.toml`, without the `v` prefix.
4. Run the workflow.

The workflow:

- verifies the requested version matches `Cargo.toml`;
- runs formatting, Clippy, tests, and documentation;
- lists the packaged files;
- runs `cargo publish --dry-run`;
- generates a CycloneDX SBOM for the release dependency graph;
- authenticates to crates.io through GitHub OIDC;
- publishes with `cargo publish`;
- creates the matching annotated Git tag;
- creates a GitHub prerelease.

The tag and GitHub release are only created after crates.io publication
succeeds.

Do not publish from an unmerged feature branch or with a version that differs
from `Cargo.toml`.

## SemVer compatibility

CI includes a `cargo-semver-checks` gate. Alpha versions are allowed to evolve
with intentional breaking changes. Beginning with beta releases, CI compares the
current public API against the latest `v*` Git tag and checks all crate
features for semantic-version compatibility.

Before preparing `0.1.0-beta.1`, make sure the latest alpha release has a
matching Git tag because that tag becomes the beta baseline.

Before publishing the first beta:

- review [BETA_MIGRATION.md]BETA_MIGRATION.md;
- confirm [PROTOCOL_STABILITY.md]PROTOCOL_STABILITY.md still matches the
  canonical envelope schema;
- run the full CI suite with the beta version in `Cargo.toml`;
- require the SemVer compatibility job to pass against the latest release tag;
- ensure the changelog documents every public API migration.

## Release provenance

The release workflow packages the crate before publication and generates a
SHA-256 checksum for the exact `.crate` archive.

It also creates a CycloneDX 1.5 SBOM for the release dependency graph and
creates signed GitHub build-provenance attestations for both the crate archive
and the SBOM.

After crates.io publication succeeds, the GitHub prerelease contains:

- `dataexcept-<version>.crate`;
- `dataexcept-<version>.crate.sha256`;
- `dataexcept-<version>.cdx.json`.

The package attestation can be verified with the GitHub CLI:

```bash
gh attestation verify dataexcept-<version>.crate \
  --repo DiogoRibeiro7/dataexcept-rs
```

The SBOM attestation can be verified with:

```bash
gh attestation verify dataexcept-<version>.cdx.json \
  --repo DiogoRibeiro7/dataexcept-rs
```

The checksum can be verified with:

```bash
sha256sum --check dataexcept-<version>.crate.sha256
```