Skip to content

Migration Guide: v0.2 to v0.3

Breaking Changes

Report.verdict() behavior change

Impact: CI pipelines that relied on Report.verdict() returning "pass" when inconclusive evidence was present will now see "inconclusive".

Before (v0.2): 

report = Report(spec_name="test", evidence=[pass_ev, inconclusive_ev])
report.verdict()  # → "pass" (inconclusive silently upgraded)

After (v0.3, strict policy — the new default): 

report = Report(spec_name="test", evidence=[pass_ev, inconclusive_ev])
report.verdict()  # → "inconclusive"

If your CI just broke, you have two options:

  1. (Recommended) Investigate the inconclusive evidence — it means "we don't know," and that's worth understanding.
  2. (Escape hatch) Restore old behavior with verdict_policy="lenient": 
    report = Report(spec_name="test", evidence=[...], verdict_policy="lenient")
report.verdict()  # → "pass" (old behavior)

Requirement.source type change

Impact: Requirement.source is now list[str] instead of str. A bare string is auto-normalized to a one-element list.

Before (v0.2): 

req.source  # → "https://example.com" (str)

After (v0.3): 

req.source  # → ["https://example.com"] (list[str])

Migration: If your code checks req.source != "", change to len(req.source) > 0. If you pass source="url" at construction time, it still works — the string is auto-normalized.

New Features (Backward-Compatible)

Catalog System

from vnvspec.catalog.ml.pytorch_training import reproducibility
from vnvspec import Spec

spec = Spec(name="my-model").extend(reproducibility())

CLI: vnvspec catalog list, vnvspec catalog show, vnvspec catalog audit, vnvspec catalog import.

New Fields and Methods

  • Report.verdict_policy: "strict" (default) or "lenient"
  • Report.inconclusive_count(): count inconclusive evidence
  • "formal_proof" is now a valid VerificationMethod and EvidenceKind

Shields.io Badge Endpoint

vnvspec export-shields-endpoint report.json -o vnv-badge.json
Use in README: ![V&V](https://img.shields.io/endpoint?url=https://<user>.github.io/<repo>/vnv-badge.json)

Upgraded GitHub Actions

The composite action now supports publish-badge, comment-pr, and verdict-policy inputs.

Backward Compatibility

  • All v0.1 and v0.2 public symbols remain importable
  • scripts/check_v0_1_compat.py and scripts/check_v0_2_compat.py run in CI
  • New fields have backward-compatible defaults
  • The catalog system is purely additive