[Pedro Henrique Penna (ppenna)]

Summary

doc/distribution.md described a source-collection behavior that has never existed, said nothing about what collect-sources needs before it runs, and stopped before the archive-release step that CI performs after every package. This PR corrects the stale claim, adds the prerequisites, and documents the archive step. It also splits the page into binary-only, source-inclusive, and archive sections. No open PR touches this file.

Changes

Statement	Evidence
Removed: "If Python initramfs variants are present, collect-sources includes their package manifests automatically." No Python initramfs variant exists, and collect-sources reads exactly one Alpine manifest (initramfs.cpio.gz.packages.json) plus the two Ubuntu manifests. The sentence dates from the initial commit, which had no such code either.	scripts/nvx_tools/release.py (collect_release_sources, _guest_release_inputs); git show 254a56c38:scripts/nvx_tools/release.py
Added: package stages dist/<version> by default, and exactly one of binary-only or source-inclusive is required.	scripts/nvx_tools/release.py (package_release); python scripts/nvx.py package --help
Added: collect-sources requires the built kernel, Alpine, and Ubuntu artifacts but not the Azure Linux ones, so build the guests first.	_guest_release_inputs(include_azurelinux=False) with ReleaseBuildConstants.GUEST_ARTIFACT_NAMES; running python scripts/nvx.py collect-sources in a clean checkout fails with required guest artifact vmlinux not found
Added: collect-sources needs Docker with the Linux engine (Alpine abuild fetch/verify in an alpine: container, plus the Docker Linux source target) and gpgv (Ubuntu InRelease verification).	scripts/nvx_tools/collect_alpine_sources.py (docker run ... alpine:); scripts/nvx_tools/build.py (build_docker_linux_source); scripts/nvx_tools/collect_ubuntu_sources.py (_verify_inrelease, require_tool(gpgv))
Added: archive-release checks the staged files against SHA256SUMS, then writes a .tar.gz or .zip archive outside the staged directory. Option details are linked to usage.md#archive-release rather than repeated.	scripts/nvx_tools/release.py (create_release_archive); python scripts/nvx.py archive-release --help
Added: On dev pushes, the linux-kvm, linux-mshv, and windows-whp platform jobs stage dist/nvx-<version>-<platform> with --binary-only and archive it as .tar.gz on Linux and .zip on Windows.	.github/actions/package-release/action.yml; .github/workflows/run-platform.yml (the push to refs/heads/dev condition); .github/workflows/ci.yml (release-platform)

No design docs changed, so no OpenVMM SHA applies. This was checked at origin/dev d8dc69f9d with OpenVMM f4566bab0.

Follow-ups

These are out of scope here because open PRs touch the files involved (#455, #406, #405, #417), or because they are code changes:

• Egress rule grammar (OpenVMM pins 3796991d5 and f4566bab0): doc/design/machine-and-device-abi.md still says generic egress rules take "optional TCP or UDP destination ports". The pinned OpenVMM also accepts protocol-only tcp/udp/icmp selectors and tcp/udp FIRST-LAST port ranges. Its fragment rule also changed: only port-specific rules make a policy reject IPv4 fragments. Update this after network: support IPv6 in the portable profile and its egress policies #455, Adopt bind-once microVM image slots #406, and test-microvm: pause and resume a microVM through OpenVMM state control #405 settle.
• Docs outside doc/: relocate scripts/setup/README.md into doc/. That requires editing links in doc/ci.md and doc/setup.md, which open PRs touch.
• Possibly stale: doc/ci.md says CI uses OPENVMM_DEPLOY_KEY "to fetch the private submodule", while doc/contribute.md and doc/project-structure.md describe a public nanvix/openvmm. Separately, the nvx.py init help text says "initialize the private submodule". That help text is in code, so it's a suspected stale string, not a doc fix.
• Repository hygiene (code, not docs): a root-level unittest_results.txt, a captured test log, has been tracked since the initial commit.
• Minor doc/project-structure.md drift: it describes doc/guests/ as "(Ubuntu)" although it also holds the Azure Linux chapter, and it lists one example under aci_edge_sandboxes/examples/ although there are two.
• doc/openvmm-upstream-roadmap.md is a dated plan pinned to fork tip 2728f33ea. Refreshing it for the current pin needs a separate analysis.

Validation

• python -m unittest scripts.test_nvx_tools.CliTests scripts.test_performance.PerformanceTests: 110 tests, OK (1 skipped)
• A throwaway link checker kept outside the repo checked doc/distribution.md and the 5 Markdown files that link to it. Every relative link and anchor resolves, the changed file has one H1 and balanced code fences, and doc/design.md links every chapter in doc/design/.
• git diff --check: clean
• python scripts/nvx.py verify: source tree and submodule metadata are consistent
• The only changed path is doc/distribution.md, so CI treats this as a documentation-only change.

[Copilot]

🟢 Approval recommended

The documentation accurately matches the packaging, source collection, archive, and CI implementations.

0 open findings

What changed in this PR

Clarifies release packaging, source collection prerequisites, and CI archive generation.

Changes:

• Separates binary-only and source-inclusive packaging guidance.
• Documents collect-sources prerequisites and removes a stale claim.
• Adds deterministic release archive and CI packaging details.

File	Description
doc/​distribution.md	Updates source-delivery prerequisites and release archive documentation.

🧠 Review effort: Balanced

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.