Skip to content

Commit 66c4649

Browse files
NafizNoyonNafizNoyon
authored
chore(release): prepare v0.1.0 engineering preview (#19)
Add release metadata, changelog, conservative release notes, release checklist, tag-triggered package validation, and release contract tests. No tag or GitHub Release is created.
1 parent be85d08 commit 66c4649

8 files changed

Lines changed: 551 additions & 2 deletions

File tree

‎.github/workflows/release.yml‎

Lines changed: 145 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,145 @@
1+
name: Release Package
2+
3+
on:
4+
push:
5+
tags:
6+
- "v*.*.*"
7+
workflow_dispatch:
8+
inputs:
9+
tag:
10+
description: Existing release tag to validate
11+
required: true
12+
type: string
13+
14+
permissions:
15+
contents: read
16+
17+
concurrency:
18+
group: release-${{ github.ref }}
19+
cancel-in-progress: false
20+
21+
jobs:
22+
package:
23+
name: Build and validate package
24+
runs-on: ubuntu-latest
25+
timeout-minutes: 30
26+
27+
steps:
28+
- name: Checkout repository
29+
uses: actions/checkout@v6
30+
31+
- name: Set up Python
32+
uses: actions/setup-python@v6
33+
with:
34+
python-version: "3.12"
35+
cache: pip
36+
cache-dependency-path: pyproject.toml
37+
38+
- name: Install release tooling
39+
run: python -m pip install --upgrade pip build twine
40+
41+
- name: Resolve release tag
42+
id: release
43+
shell: bash
44+
run: |
45+
if [[ "${{ github.event_name }}" == "workflow_dispatch" ]]; then
46+
echo "tag=${{ inputs.tag }}" >> "$GITHUB_OUTPUT"
47+
else
48+
echo "tag=${GITHUB_REF_NAME}" >> "$GITHUB_OUTPUT"
49+
fi
50+
51+
- name: Verify tag and source versions
52+
env:
53+
RELEASE_TAG: ${{ steps.release.outputs.tag }}
54+
run: |
55+
python - <<'PY'
56+
import ast
57+
import os
58+
import tomllib
59+
from pathlib import Path
60+
61+
metadata = tomllib.loads(
62+
Path("pyproject.toml").read_text(encoding="utf-8")
63+
)
64+
package_version = metadata["project"]["version"]
65+
66+
module = ast.parse(
67+
Path(
68+
"src/edge_traffic_vision/__init__.py"
69+
).read_text(encoding="utf-8")
70+
)
71+
72+
version_assignments = [
73+
node
74+
for node in module.body
75+
if isinstance(node, ast.Assign)
76+
and any(
77+
isinstance(target, ast.Name)
78+
and target.id == "__version__"
79+
for target in node.targets
80+
)
81+
]
82+
83+
if len(version_assignments) != 1:
84+
raise SystemExit(
85+
"Expected exactly one __version__ assignment"
86+
)
87+
88+
source_version = ast.literal_eval(
89+
version_assignments[0].value
90+
)
91+
92+
expected_tag = f"v{package_version}"
93+
release_tag = os.environ["RELEASE_TAG"]
94+
95+
if release_tag != expected_tag:
96+
raise SystemExit(
97+
f"Tag mismatch: expected {expected_tag}, "
98+
f"received {release_tag}"
99+
)
100+
101+
if source_version != package_version:
102+
raise SystemExit(
103+
f"Source version {source_version} does not match "
104+
f"metadata version {package_version}"
105+
)
106+
107+
print(f"Version contract verified: {release_tag}")
108+
PY
109+
110+
- name: Build distributions
111+
run: python -m build
112+
113+
- name: Validate distributions
114+
run: python -m twine check dist/*
115+
116+
- name: Install built wheel
117+
run: python -m pip install --no-deps --force-reinstall dist/*.whl
118+
119+
- name: Verify installed package version
120+
env:
121+
RELEASE_TAG: ${{ steps.release.outputs.tag }}
122+
run: |
123+
python - <<'PY'
124+
import os
125+
126+
import edge_traffic_vision
127+
128+
expected = os.environ["RELEASE_TAG"].removeprefix("v")
129+
actual = edge_traffic_vision.__version__
130+
131+
if actual != expected:
132+
raise SystemExit(
133+
f"Installed version {actual} does not match {expected}"
134+
)
135+
136+
print(f"Installed package version verified: {actual}")
137+
PY
138+
139+
- name: Upload release distributions
140+
uses: actions/upload-artifact@v4
141+
with:
142+
name: edge-traffic-vision-${{ steps.release.outputs.tag }}
143+
path: dist/*
144+
if-no-files-found: error
145+
retention-days: 14

‎CHANGELOG.md‎

Lines changed: 57 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,57 @@
1+
# Changelog
2+
3+
All notable changes to Edge Traffic Vision are documented in this file.
4+
5+
The project follows semantic versioning for repository releases. The
6+
changelog records engineering evidence and does not imply production
7+
readiness.
8+
9+
## [Unreleased]
10+
11+
### Pending
12+
13+
- Continuous road-video validation using a naturally changing video source
14+
- Repository license selection and addition
15+
- Final decision on whether version 0.1.0 is a normal or prerelease release
16+
17+
## [0.1.0] - 2026-08-06
18+
19+
### Added
20+
21+
- Repository, package, configuration, and test foundations
22+
- Deterministic BDD100K ingestion and dataset validation
23+
- Annotation-balanced pilot selection across ten road-object classes
24+
- CPU training readiness, smoke training, and controlled 40-epoch training
25+
- Confidence-threshold operating-point selection
26+
- Reproducible ONNX export and artifact validation
27+
- PyTorch and ONNX Runtime raw-backend comparison
28+
- Low-light, blur, and Gaussian-noise robustness evaluation
29+
- Config-driven ONNX Runtime video and camera inference
30+
- Warm-up-aware component and source-to-output video profiling
31+
- Representative 360p, 720p, and 1080p multi-scene validation
32+
- CPU-only, non-root Docker packaging
33+
- GitHub Actions tests, linting, Docker build, and smoke validation
34+
- Release metadata, release notes, checklist, and package-build workflow
35+
36+
### Verified engineering results
37+
38+
- Balanced pilot: 2,500 images and 45,443 annotations
39+
- Selected 40-epoch model: mAP50 0.14127 and mAP50-95 0.07561
40+
- Selected confidence 0.20: precision 0.51974, recall 0.32730,
41+
and F1 0.40166
42+
- Controlled ONNX Runtime raw-backend speedup: 3.317x
43+
- Largest measured robustness weakness: Gaussian noise
44+
- Severe Gaussian-noise mAP50 drop: 39.71 percent
45+
- Representative video validation completed at 360p, 720p, and 1080p
46+
- Docker image build and smoke checks passed in GitHub Actions
47+
48+
### Known limitations
49+
50+
- The trained model, ONNX artifact, datasets, videos, and generated reports
51+
are not bundled with the source package
52+
- Continuous real road-video validation remains pending
53+
- Webcam and camera-device forwarding remain environment-dependent
54+
- Results are based on a limited balanced pilot rather than full-scale
55+
production training
56+
- The current runtime is CPU-only
57+
- The repository license has not yet been selected

‎README.md‎

Lines changed: 17 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,21 @@ videos.
77
The repository emphasizes reproducibility, automated validation, measurable
88
performance, and deployment-oriented engineering.
99

10+
11+
## Release Status
12+
13+
- Package metadata version: `0.1.0`
14+
- Release stage: engineering-preview preparation
15+
- Public GitHub Release: not published
16+
- Continuous road-video validation: pending until a suitable MP4 is supplied
17+
- Repository license selection: pending
18+
- Model, dataset, video, and generated report artifacts: not bundled
19+
20+
Release preparation is documented in
21+
[Release Checklist](docs/release_checklist.md), while the proposed
22+
version-specific notes are in
23+
[v0.1.0 Release Notes](docs/releases/v0.1.0.md).
24+
1025
## Project Goals
1126

1227
- Fine-tune a lightweight object-detection model
@@ -288,11 +303,12 @@ Completed milestones:
288303
15. Warm-up-aware end-to-end video pipeline optimization
289304
16. Representative multi-scene and resolution video validation
290305
17. CPU-only non-root Docker packaging and CI image validation
306+
18. Versioned release metadata and package-build preparation
291307

292308
Current milestone:
293309

294310
```text
295-
Docker packaging completed -> continuous road-video or webcam validation -> release polish
311+
release preparation in progress -> continuous road-video validation -> v0.1.0 release decision
296312
```
297313

298314
## Planned Technology Stack

‎docs/release_checklist.md‎

Lines changed: 80 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,80 @@
1+
# Release Checklist
2+
3+
This checklist prepares version `0.1.0`. Creating the preparation pull
4+
request does not create a tag or GitHub Release.
5+
6+
## Blocking decisions
7+
8+
- [ ] Select and add an appropriate repository license
9+
- [ ] Complete continuous road-video validation using a user-supplied MP4,
10+
or explicitly classify version 0.1.0 as a prerelease
11+
- [ ] Review model and dataset redistribution restrictions
12+
- [ ] Review `docs/releases/v0.1.0.md`
13+
- [ ] Confirm the release commit contains no private or generated artifacts
14+
15+
## Repository validation
16+
17+
- [ ] `main` is clean and synchronized with `origin/main`
18+
- [ ] Full Pytest suite passes
19+
- [ ] Ruff passes
20+
- [ ] Docker build and smoke job passes
21+
- [ ] Package version equals `0.1.0`
22+
- [ ] Package `__version__` equals `0.1.0`
23+
- [ ] Changelog contains the `0.1.0` entry
24+
- [ ] Release workflow validates the tag against package metadata
25+
26+
## Tag preparation
27+
28+
Run these commands only after every blocking decision is resolved:
29+
30+
```powershell
31+
git switch main
32+
git pull --ff-only origin main
33+
git status -sb
34+
35+
git tag -a v0.1.0 -m "Edge Traffic Vision v0.1.0"
36+
git push origin v0.1.0
37+
```
38+
39+
The `Release Package` workflow will:
40+
41+
1. Verify that the tag matches package metadata.
42+
2. Build the source distribution and wheel.
43+
3. Validate both distributions with Twine.
44+
4. Install the wheel without dependencies.
45+
5. Verify the installed package version.
46+
6. Upload the distributions as a workflow artifact.
47+
48+
## GitHub Release creation
49+
50+
After the tag workflow passes, obtain the package artifact and create the
51+
GitHub Release manually:
52+
53+
```powershell
54+
gh run list `
55+
--repo NafizNoyon/edge-traffic-vision `
56+
--workflow release.yml `
57+
--limit 5
58+
59+
gh run download <RUN_ID> `
60+
--repo NafizNoyon/edge-traffic-vision `
61+
--name edge-traffic-vision-v0.1.0 `
62+
--dir release-dist
63+
64+
gh release create v0.1.0 `
65+
--repo NafizNoyon/edge-traffic-vision `
66+
--title "Edge Traffic Vision v0.1.0" `
67+
--notes-file docs/releases/v0.1.0.md `
68+
release-dist/*
69+
```
70+
71+
Add `--prerelease` to `gh release create` when continuous road-video
72+
validation remains incomplete.
73+
74+
## Post-release verification
75+
76+
- [ ] GitHub Release points to the intended tag
77+
- [ ] Source archive is available
78+
- [ ] Wheel and source distribution are attached
79+
- [ ] Release notes show the known limitations
80+
- [ ] No model or dataset artifact was accidentally published

‎docs/releases/v0.1.0.md‎

Lines changed: 71 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,71 @@
1+
# Edge Traffic Vision v0.1.0
2+
3+
## Release type
4+
5+
Version 0.1.0 is prepared as an engineering-preview release. It demonstrates
6+
a reproducible end-to-end edge traffic-vision workflow but must not be
7+
described as production-ready.
8+
9+
## Included capabilities
10+
11+
- Deterministic BDD100K ingestion and YOLO conversion
12+
- Dataset-quality validation with JSON and CSV reporting
13+
- Annotation-balanced ten-class pilot construction
14+
- CPU training readiness and controlled fine-tuning
15+
- Model evaluation and confidence-threshold selection
16+
- ONNX export, runtime validation, and backend benchmarking
17+
- Low-light, blur, and Gaussian-noise robustness evaluation
18+
- ONNX Runtime video inference with annotated MP4 output
19+
- Warm-up-aware decode, inference, rendering, writing, and total latency
20+
- Representative 360p, 720p, and 1080p multi-scene video validation
21+
- CPU-only non-root Docker packaging
22+
- GitHub Actions Python and Docker validation
23+
24+
## Selected evidence
25+
26+
| Item | Verified result |
27+
|---|---:|
28+
| Balanced images | 2,500 |
29+
| Balanced annotations | 45,443 |
30+
| Classes | 10 |
31+
| 40-epoch mAP50 | 0.14127 |
32+
| 40-epoch mAP50-95 | 0.07561 |
33+
| Selected confidence | 0.20 |
34+
| Selected F1 | 0.40166 |
35+
| Raw ONNX Runtime speedup | 3.317x |
36+
| Worst severe-noise mAP50 drop | 39.71% |
37+
| Validated resolutions | 360p, 720p, 1080p |
38+
| Docker CI build | Passed |
39+
40+
## Artifact policy
41+
42+
This repository release does not bundle:
43+
44+
- BDD100K data
45+
- PyTorch checkpoints
46+
- ONNX model files
47+
- Input or annotated videos
48+
- Generated reports
49+
- Private environment configuration
50+
51+
Model and data artifacts must be supplied separately and must follow their
52+
respective licensing and distribution terms.
53+
54+
## Remaining blockers
55+
56+
The following items must be resolved or explicitly accepted before the tag
57+
is published:
58+
59+
1. Select and add a repository license.
60+
2. Complete continuous road-video validation when a suitable MP4 is
61+
available, or mark the GitHub release as a prerelease.
62+
3. Review this release note against the final main commit.
63+
4. Confirm that no dataset, model, report, secret, or local environment file
64+
is included.
65+
5. Confirm both Python and Docker CI jobs pass on the release commit.
66+
67+
## Reproducibility statement
68+
69+
The source repository contains configuration, tests, documentation, and
70+
packaging definitions. Large datasets and trained model artifacts remain
71+
external by design.

0 commit comments

Comments
 (0)