Development Testing and Releases

Development, testing, and releases

Repository layout

Path	Contents
source/	Slackware package filesystem tree and implementation.
plugin/dvm.plg	Install/update/remove manifest and changelog.
plugin/dvm.png	Repository plugin icon.
packages/	Required vnStat dependency archive.
packages/sources/	Corresponding vnStat source, signature, and upstream public signing key.
packages/vnstat-2.14-build.json	Dependency source/toolchain inputs, executable hashes, and ABI metadata.
archive/	Plugin package and checksum sidecars.
scripts/build_package.py	Deterministic builder with staged output/recovery.
scripts/build_vnstat.py	Pinned Linux build for the vnStat dependency.
scripts/validate_repository.py	Shared local/CI syntax, regression, tracking, and package checks.
scripts/release_channel.py	Shared channel URL and release-metadata rules.
scripts/prepare_release.py	Isolated candidate preparation, dry-run reporting, and guarded generated-file updates.
.github/workflows/validate.yml	Validation for pushes and pull requests targeting main.
tests/	Isolated regressions and bundled-binary integration tests.

Review and test

Read affected code and callers before changes. Reproduce bugs, review the fix, run its regression afterward, and check persistence, errors, and connected behavior. Commands and coverage for the initial audit and subsequent improvements are documented in tests/README.md.

The full suite needs Linux, Python 3, Bash, flock, PHP CLI with SimpleXML, and Node.js. Native tests currently use /usr/bin/php8.3. On Windows, use WSL for Linux-dependent suites; JavaScript tests can use Windows Node.js. Skipped platform-specific tests do not validate the skipped behavior.

Tests use temporary paths and mocked workloads. Native vnStat tests extract the bundled binaries and initialize an isolated database without starting a daemon. Fixture results do not establish live Unraid acceptance.

After building the candidate package, run the same check used by GitHub Actions:

python3 scripts/validate_repository.py --channel dev

Use --channel main for a final Stable candidate. Explicit channel selection also works in detached checkouts; a branch name alone is not evidence that the manifest and packaged metadata point to the correct channel. Run validation as an unprivileged Linux user. It checks PHP/Bash/JavaScript syntax and ShellCheck warnings, discovers all Python/PHP/JavaScript regressions, rejects skipped Python tests and tracked ignored files, and verifies manifest downloads, checksums, archive inventory/bytes/permissions, icon consistency, and a reproducible rebuild. CI uses Ubuntu 24.04, Python 3.12, PHP 8.3 with SimpleXML, and Node.js 24. A local pass and the hosted result apply to the tested commit; live Unraid acceptance remains separate.

Build

The bundled backend is built from the signed upstream 2.14 release. Its corresponding source and detached signature are included in the repository. To rebuild it as an unprivileged Linux user, install Python 3.12+, make, GnuPG, and readelf (binutils), then run:

python3 scripts/build_vnstat.py

The build verifies the source SHA-256 and pinned upstream signing fingerprint 23EF1DD76E65248FB055201ADAFE84E63D140114. It downloads a pinned Zig/LLVM toolchain and checksum-pinned baseline GD/SQLite headers and link libraries into ~/.cache/dvm-vnstat-build/ (override with --cache PATH). Build inputs remain in that local cache; host libraries are not shipped. Builds occur in fresh isolated directories and do not run make install or start a service. Executables must pass x86_64, GLIBC symbol, library dependency, and embedded-path checks before publication. Package ownership/modes/timestamps are deterministic, and GPL license, upstream documentation, and manpages are included.

The builder writes the dependency archive, MD5/SHA-256 sidecars, and build metadata. Update the dependency identity/MD5 in the plugin manifest when introducing a new backend build. The old 2.12 archive is retained for historical downloads and isolated database/threshold compatibility tests.

The 2.14 upgrade retains saved configuration and traffic databases. New installs and resets receive a configuration documenting the new optional settings while retaining DVM's collection/save intervals and automatic-interface defaults. Native qualification covers reading a 2.12 database without losing its traffic history; vnStat updates its own version metadata. Keep an independent backup when testing upgrades on a real host.

After validation, run from the repository root with Python 3:

python scripts/build_package.py

The builder reads the manifest's package identity, assembles source with deterministic ownership/modes/timestamps and Unix text line endings, creates .txz, .txz.md5, and .txz.sha256, and updates the manifest MD5. It rejects missing required payloads, symlinks, and unreadable directories; stages outputs; and restores previous files on handled replacement failures. Failed rollback retains recovery files. Multiple outputs are not a power-loss transaction.

Commit matching packages/checksums with source and manifest changes. For a new distributed build, update the version/package identity rather than replacing an artifact already installed by users.

Branch and publication workflow

Completed updates target dev. Installer/download/update URLs must use dev. Promotion to main or a stable release requires an explicit maintainer request.

Release preparation accepts only the dev and main channels. It renders the manifest and packaged release.json from the same channel/version pair, keeps the identity dvm, and validates all final download/update URLs and package contents. Installed plugins do not inspect Git repositories to discover their channel.

Use a newer, consistently zero-padded YYYY.MM.DD.NN date/build version, such as 2026.11.04.10; do not reuse a published version for changed package bytes. Preparation checks the calendar date and requires changed release pairs to order after the current version and every existing plugin archive, both numerically and in Unraid's version-string comparison. Every preparation mode requires a new version, including dry-run. A stable promotion should use a fresh version above the development version being promoted. Use build_package.py to reproduce an existing exact candidate; an identical rebuild is not a new release and must not replace published bytes with changed content.

To review a candidate without changing the checkout, substitute a new numeric version in these commands:

python3 scripts/prepare_release.py --channel main --version NEW_VERSION --dry-run
python3 scripts/prepare_release.py --channel main --version NEW_VERSION --output /tmp/dvm-stable-candidate
python3 /tmp/dvm-stable-candidate/scripts/validate_repository.py --channel main

NEW_VERSION is a placeholder, not a literal accepted version. Dry-run is also the default when no output/apply mode is selected. --dry-run builds an isolated candidate, runs its package/tracking checks, and prints its plan. --output prepares a complete candidate outside the repository and refuses to overwrite an existing destination. Neither mode merges, commits, pushes, or promotes a branch. Run the separate full validation command against the output candidate; preparation's package checks do not replace its regression suite.

Use --notes-file PATH to supply UTF-8 Markdown bullet notes for the new manifest changelog. Read and review the generated notes with the package plan.

--apply updates generated release files transactionally only from a named checkout matching the chosen channel. Do not apply a main candidate to a dev checkout. For a separately authorized promotion, prepare the approved main checkout, apply the new main-channel release there, run final validation, review/commit the exact candidate, and publish it through main's checks. Keep dev metadata on dev when synchronizing code back afterward. Preparation is not authorization to merge or publish main.

The maintainer requires --no-verify for development commits/pushes. Development updates do not trigger hosted checks, and development runs are not monitored. GitHub Actions checks apply to main and pull requests targeting main, once the workflow is included in that branch. Run applicable local regressions for code changes before publishing:

git switch dev
# Review, test, and verify the package before staging reviewed paths.
git add <reviewed-paths>
git commit --no-verify -m "Describe the change"
git push --no-verify origin dev

Track source, tests, documentation, required .txz archives, and checksums. .gitignore excludes environments, caches, editor files, credentials, logs, temporary/recovery files, runtime databases, and local support exports. Required packages, release archives, shipped assets, and matching checksums remain tracked.

Documentation and qualification

The first stable release is 2026.11.04.11. Its release notes contain the cumulative changes from the original plugin.

Keep these wiki pages, the repository README, installed README links, and test instructions aligned with the implemented release. Main CI checks the actual stable candidate, including canonical URLs and packaged release metadata. Hypothetically rendering a stable manifest is not evidence that a published development manifest has been corrected.

No stable promotion, branch merge, tag, release, or public artifact is implied by preparing a candidate. Publication requires the maintainer's separate instruction. Record live-host observations separately in Host acceptance.