Skip to content

Commit 7fa3da5

Browse files
greyllmmodergreyllmmoder
committed
chore: add conformance evidence tooling and release gates
1 parent 0e71673 commit 7fa3da5

9 files changed

Lines changed: 526 additions & 1 deletion

File tree

‎.github/workflows/ci.yml‎

Lines changed: 36 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,9 @@ on:
44
push:
55
pull_request:
66

7+
permissions:
8+
contents: read
9+
710
jobs:
811
test:
912
runs-on: ubuntu-latest
@@ -29,6 +32,38 @@ jobs:
2932
run: |
3033
pytest -q
3134
35+
conformance:
36+
runs-on: ubuntu-latest
37+
needs: test
38+
steps:
39+
- uses: actions/checkout@v4
40+
41+
- name: Set up Python
42+
uses: actions/setup-python@v5
43+
with:
44+
python-version: "3.11"
45+
46+
- name: Install dependencies
47+
run: |
48+
python -m pip install --upgrade pip
49+
python -m pip install -e ".[dev,image,pdf]"
50+
51+
- name: Generate conformance evidence
52+
run: |
53+
python scripts/conformance_report.py \
54+
--report conformance_report.md \
55+
--json conformance_report.json \
56+
--matrix-report compat_matrix_report.md
57+
58+
- name: Upload conformance artifacts
59+
uses: actions/upload-artifact@v4
60+
with:
61+
name: conformance-evidence
62+
path: |
63+
conformance_report.md
64+
conformance_report.json
65+
compat_matrix_report.md
66+
3267
quality:
3368
runs-on: ubuntu-latest
3469
needs: test
@@ -55,7 +90,7 @@ jobs:
5590
5691
build:
5792
runs-on: ubuntu-latest
58-
needs: quality
93+
needs: [quality, conformance]
5994
steps:
6095
- uses: actions/checkout@v4
6196

‎.github/workflows/release-gate.yml‎

Lines changed: 55 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,55 @@
1+
name: release-gate
2+
3+
on:
4+
workflow_dispatch:
5+
release:
6+
types: [published, prereleased]
7+
8+
permissions:
9+
contents: read
10+
11+
jobs:
12+
gate:
13+
runs-on: ubuntu-latest
14+
15+
steps:
16+
- uses: actions/checkout@v4
17+
18+
- name: Set up Python
19+
uses: actions/setup-python@v5
20+
with:
21+
python-version: "3.11"
22+
23+
- name: Install dependencies
24+
run: |
25+
python -m pip install --upgrade pip
26+
python -m pip install -e ".[dev,image,pdf]"
27+
python -m pip install build twine
28+
29+
- name: Quality gates
30+
run: |
31+
pytest -q
32+
ruff check .
33+
mypy --strict aztec_py
34+
35+
- name: Conformance evidence
36+
run: |
37+
python scripts/conformance_report.py \
38+
--report conformance_report.md \
39+
--json conformance_report.json \
40+
--matrix-report compat_matrix_report.md
41+
42+
- name: Build and verify artifacts
43+
run: |
44+
python -m build
45+
twine check dist/*
46+
47+
- name: Upload release gate artifacts
48+
uses: actions/upload-artifact@v4
49+
with:
50+
name: release-gate-evidence
51+
path: |
52+
conformance_report.md
53+
conformance_report.json
54+
compat_matrix_report.md
55+
dist/*

‎.gitignore‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -40,6 +40,9 @@ htmlcov/
4040
.coverage
4141
.coverage.*
4242
.cache
43+
compat_matrix_report.md
44+
conformance_report.md
45+
conformance_report.json
4346
nosetests.xml
4447
coverage.xml
4548
*,cover

‎MANIFEST.in‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3,3 +3,4 @@ include requirements.txt
33
include LICENSE
44
include LICENSE.upstream
55
include CONTRIBUTORS.md
6+
include docs/ISO_IEC_24778_TRACEABILITY.md

‎PRODUCTION_CHECKLIST.md‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -9,7 +9,9 @@ Use this checklist before shipping a new `aztec-py` version to production.
99
- [ ] `python -m mypy --strict aztec_py`
1010
- [ ] `python -m build`
1111
- [ ] `python scripts/decoder_matrix.py --report compat_matrix_report.md`
12+
- [ ] `python scripts/conformance_report.py --report conformance_report.md --json conformance_report.json --matrix-report compat_matrix_report.md`
1213
- [ ] If decode runtime is available in CI: `python scripts/decoder_matrix.py --strict-decode`
14+
- [ ] `docs/ISO_IEC_24778_TRACEABILITY.md` reviewed and current
1315

1416
## 2. Runtime Optional Dependencies
1517

@@ -42,5 +44,6 @@ Use this checklist before shipping a new `aztec-py` version to production.
4244
## 6. Incident Guardrails
4345

4446
- [ ] Keep compatibility fixture failures as release blockers.
47+
- [ ] Keep conformance report failures as release blockers.
4548
- [ ] Log scanner model/runtime for each production decode issue.
4649
- [ ] Add a regression fixture for every production bug before patching.

‎README.md‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -79,7 +79,17 @@ Use strict mode when decode checks are mandatory in CI:
7979
python scripts/decoder_matrix.py --strict-decode
8080
```
8181

82+
Generate full conformance evidence (markdown + JSON + compatibility matrix):
83+
84+
```bash
85+
python scripts/conformance_report.py \
86+
--report conformance_report.md \
87+
--json conformance_report.json \
88+
--matrix-report compat_matrix_report.md
89+
```
90+
8291
Fixture source: `tests/compat/fixtures.json`
92+
Traceability matrix: `docs/ISO_IEC_24778_TRACEABILITY.md`
8393
Release checklist: `PRODUCTION_CHECKLIST.md`
8494

8595
## CLI

‎docs/ISO_IEC_24778_TRACEABILITY.md‎

Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,41 @@
1+
# ISO/IEC 24778 Traceability Matrix
2+
3+
This document provides implementation traceability evidence for `aztec-py`.
4+
It is intended for audit support and release validation workflows.
5+
6+
This matrix does not replace independent certification.
7+
8+
## Scope
9+
10+
- Encoder implementation: `aztec_py/core.py`
11+
- Symbol rendering: `aztec_py/renderers/*`
12+
- Validation fixtures and regression checks: `tests/*`, `tests/compat/fixtures.json`
13+
14+
## Traceability Table
15+
16+
| Requirement Area | Implementation Evidence | Automated Verification |
17+
|---|---|---|
18+
| Symbol layer/size selection and capacity fit checks | `aztec_py/core.py` (`find_suitable_matrix_size`, `_required_capacity_bits`) | `tests/test_core.py`, `tests/test_validation.py` |
19+
| Reed-Solomon error correction generation | `aztec_py/core.py` (`reed_solomon`) | `tests/test_core.py::Test::test_reed_solomon` |
20+
| Character mode/latch/shift sequencing | `aztec_py/core.py` (`find_optimal_sequence`, `optimal_sequence_to_bits`) | `tests/test_core.py::Test::test_find_optimal_sequence_*`, `tests/test_core.py::Test::test_optimal_sequence_to_bits` |
21+
| Bit stuffing and codeword construction | `aztec_py/core.py` (`get_data_codewords`) | `tests/test_core.py::Test::test_get_data_codewords` |
22+
| CRLF handling regression | `aztec_py/core.py` + fixture/test coverage | `tests/test_core.py::Test::test_crlf_encoding`, `tests/test_core.py::Test::test_crlf_roundtrip` |
23+
| Error-correction capacity regression (worst-case bytes) | `aztec_py/core.py` capacity calculations | `tests/test_core.py::Test::test_ec_worst_case_ff_bytes`, `tests/test_core.py::Test::test_ec_worst_case_null_bytes` |
24+
| GS1 payload composition and separators | `aztec_py/gs1.py` | `tests/test_gs1.py` |
25+
| Rendering determinism (PNG/SVG/PDF) | `aztec_py/core.py`, `aztec_py/renderers/image.py`, `aztec_py/renderers/svg.py` | `tests/test_renderers.py`, `tests/test_api_behaviour.py` |
26+
| CLI behavior and output contract | `aztec_py/__main__.py` | `tests/test_cli.py` |
27+
| Compatibility fixture corpus and decode matrix | `scripts/decoder_matrix.py`, `tests/compat/fixtures.json` | `tests/test_compat_matrix.py`, `scripts/conformance_report.py` |
28+
29+
## Release Evidence Artifacts
30+
31+
The following artifacts are generated and retained by CI/release gates:
32+
33+
- `compat_matrix_report.md`
34+
- `conformance_report.md`
35+
- `conformance_report.json`
36+
37+
## Audit Notes
38+
39+
- Decode checks are runtime-dependent (`python-zxing` + Java).
40+
- Non-strict mode allows skip-safe evidence generation when decode backend is unavailable.
41+
- Strict mode can be enabled for environments where decode runtime is mandatory.

0 commit comments

Comments
 (0)