Releases and documentation synchronization

Package release path

In the documented release, v0.1.16, creating a GitHub Release triggers the publication workflow. It runs the reusable validation workflow (tests, lint, format checks, and a package build), then builds source and wheel distributions and publishes them to PyPI using OIDC trusted publishing.

The publication environment is named release. This release does not generate a documentation asset bundle.

Pre-release verification

Run these checks locally before creating the release; the publication workflow also validates the source:

python -m pytest
python -m build

Then inspect:

• generated source and wheel contents;
• dynamic version;
• importability from the wheel;
• public examples;
• optional plotting imports; and
• release notes.

Create a tag that setuptools-scm resolves to the intended package version.

Documentation release selection

This site does not automatically follow the highest semantic version or default branch.

Select the qualifying release with the most recent GitHub created_at timestamp where:

draft = false
prerelease = false

Resolve its exact tag target and commit.

Audit before synchronizing

For a new stable release, inspect at least:

README.md
pyproject.toml
model_auditor/__init__.py
model_auditor/core.py
model_auditor/metrics.py
model_auditor/metric_inputs.py
model_auditor/error_metrics.py
model_auditor/schemas.py
model_auditor/plotting/
tests/
.github/workflows/

Compare:

• public signatures and defaults;
• result fields and export columns;
• error types and messages;
• metric formulas;
• threshold precedence;
• bootstrap semantics;
• null/categorical behavior;
• optional dependency behavior;
• test coverage; and
• known limitations.

Update one source record

Change every field in docs-source.json together:

{
  "repository": "beatrice-b-m/model-auditor",
  "release": "vX.Y.Z",
  "commit": "<exact commit>",
  "synchronizedAt": "<UTC ISO 8601 timestamp>"
}

Update all affected pages in the same pull request. Do not change only the release label.

Documentation validation

npm run format
npm run validate

Review:

• formatting and code-fence checks;
• site config and provenance validation;
• Astro diagnostics;
• production build;
• generated internal links;
• Linux npm ci; and
• Cloudflare preview.

Handling a release with incomplete or conflicting behavior

Document observed stable behavior rather than silently repairing it in prose.

When source, tests, README, and docstrings disagree:

1. prioritize executable stable source and deterministic tests;
2. record the discrepancy for maintainers;
3. disclose user-relevant limitations at the affected page;
4. avoid promising intended but unimplemented behavior; and
5. remove the caveat only after a later stable release verifies the change.

Merge and deployment

Merge the synchronization pull request only when:

• provenance matches the selected tag;
• examples are verified;
• limitations are accurate;
• all repository checks pass; and
• the preview is complete.

Cloudflare deploys the static site from main according to the documentation repository’s build configuration.