Releases and documentation synchronization

Package release path

The stable source workflow is triggered when a GitHub Release is created.

It:

1. checks out the repository;
2. sets up Python;
3. installs build tooling;
4. runs python -m build; and
5. publishes distributions to PyPI with OIDC trusted publishing.

The workflow environment is named release, and its public environment URL points to the PyPI project.

Pre-release verification

Because the stable publication workflow does not execute tests, complete these checks before creating the release:

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.