tasty-bdd-0.2.0.0: docs/releases.md

# Prepare and publish a release

## Review a package before publication

As a maintainer, you need a checked source distribution and a deliberate version choice before publishing a package used by others.

```mermaid
flowchart LR
  Checks -->|pass| Archives
  Archives -->|review contents and rebuild| Maintainer
  Maintainer -->|upload source and documentation| Hackage
  Maintainer -->|tag released commit| Tag
```

Run `nix develop --accept-flake-config -c just release-check` to create checked source and Hackage-mode Haddock archives plus `SHA256SUMS` in `result-release`. The `hackage-quality` gate unpacks the source archive, runs `cabal check`, builds and tests with the consumer warning policy, and requires 100% Haddock coverage for every module with no unresolved local references. It runs offline against the locked dependency environment and is required by CI. Building the archives does not publish a package; publication is a manual upload of those archives.

## How 0.1.0.2 was published

Version 0.1.0.2 was uploaded to [Hackage](https://hackage.haskell.org/package/tasty-bdd-0.1.0.2) on 2026-10-01 with documentation.

- Both archives are the outputs of `nix build .#hackage-release`, the build `just release-check` runs.
- The source archive was uploaded with `cabal upload --publish` and the documentation archive with `cabal upload --publish -d`.
- The sha256 of the uploaded tarball, `2c8170f6f7e3279a968745ece3e988a3f8f38718db9ddf0f34844dd4cec5dbf3`, equals the `SHA256SUMS` entry of the local build.
- The annotated tag `v0.1.0.2` points at commit 0836274.

## Hackage links and automation

Repository ownership does not change Hackage ownership or existing package descriptions. Hackage 0.1.0.1 currently points to GitLab. A GitHub transfer alone will not update those links. Existing Hackage tarballs remain historical artifacts.

The release workflow prepares an archive for review and never uploads to Hackage. No automatic tagging or package publication is enabled by this modernization.

External dependency links in the optional Haddock bundle depend on installed dependency interfaces; missing external interfaces do not waive the package’s own documentation coverage.

Every library, whether published or unpublished, has its current generated API embedded in the documentation. For tasty-bdd, the [API reference](api.md) embeds the same Haddock bundle checked for release. CI verifies every embedded file and local API link; deployment compares the served API and source pages with that build.