Skip to content

Migration Guide: v0.1 → v0.2

v0.2 is a fully backward-compatible upgrade. No code changes required for the upgrade itself.

Upgrade

pip install --upgrade vnvspec

What changed

Evidence.details accepts str | dict (no migration needed)

# v0.1 — only dict
Evidence(..., details={"message": "ok"})

# v0.2 — str also works (auto-wrapped to {"message": "..."})
Evidence(..., details="ok")
# Result: details == {"message": "ok"}

Report.summary accepts str | dict (no migration needed)

Same pattern as Evidence.details.

Structured exit codes

If your CI scripts check for non-zero exit codes from vnvspec commands, the specific exit code values have changed:

Code Meaning
0 OK
1 Assessment failures
2 Inconclusive
3 Spec validation error
4 Usage error
5 Internal error

If you were checking exit code != 0 generically, no change needed.

Before (v0.1): 

evidence = []
evidence.append(Evidence(id="EV-1", requirement_id="REQ-001", kind="test",
                         verdict="pass", details={"message": "ok"}))
evidence.append(Evidence(id="EV-2", requirement_id="REQ-002", kind="test",
                         verdict="fail", details={"message": "too slow"}))
report = Report(spec_name="my-spec", evidence=evidence)

After (v0.2): 

with EvidenceCollector(spec) as c:
    c.check("REQ-001", accuracy > 0.9, message="accuracy check")
    c.check("REQ-002", latency < 100, message="latency check")
report = c.build_report()

YAML/TOML spec format

Specs can now be defined in YAML or TOML instead of Python:

spec = Spec.from_yaml("spec.yaml")
spec = Spec.from_toml("spec.toml")

GtWR profiles

Default behavior unchanged. Optionally pass a profile:

violations = req.check_quality(profile=RuleProfile.WEB_APP)

Or via CLI: 

vnvspec validate --profile web-app spec.yaml

New features (opt-in)

  • Spec.extend() for composing catalog modules
  • vnvspec.catalog.demo (preview namespace for v0.3)
  • Compliance matrix exporter (export_compliance_matrix())
  • standard_gap_analysis() for coverage analysis
  • pytest-vnvspec plugin (pip install pytest-vnvspec)
  • auto_trace() for regex-based traceability
  • Badge SVG exporter
  • Report diff for regression detection