Harden release packaging and recoverable installation after review

This commit is contained in:
bholman committed 2026-11-18 16:26:25 -07:00
1 parent cb40fed3b9
commit 8088c1fbf6
14 files changed
+933 -101

No files matched your search

+54 -1
View File
@@ -6,6 +6,24 @@ Use 64-bit Windows, Git for Windows and Python **3.10 or newer**. Scripts use th
Python standard library. PowerShell wrappers accept `-Python <full-path>` when
`python` is not on PATH. All commands below run from the repository root.
Use a full Git checkout. An extracted source-review ZIP has no `.git` metadata
and deliberately omits inherited binary/manual artifacts still present in the
historical project inventory; it is not the supported build checkout. A release's
`SOURCE-CHECKOUT.txt` gives the exact immutable revision and clone commands:
```powershell
git clone https://vccplus-git.brianholman.com/VCCPlus/CoCo3_Plus_MiSTer.git coco3plus
cd coco3plus
# Replace RELEASE_SOURCE_REVISION with the full hash in SOURCE-CHECKOUT.txt.
git checkout --detach RELEASE_SOURCE_REVISION
git rev-parse HEAD
```
Do not pass `--depth`; the clone preserves the original upstream history. Access
to the repository is required. Build tools invoke Git to record the source
revision; merely installing the Git executable does not make an archive a Git
checkout. Keep the pinned checkout unchanged while building and qualifying it.
Install **Quartus Prime Lite 17.0.2, Build 602**, including Cyclone V device files.
The device is **5CSEBA6U23I7**. The project originated in Quartus 17.0; its pinned
settings record 17.0.2. Install the 17.0 base package and matching device package,
@@ -71,6 +89,9 @@ the maintained `tools/project_inputs.json` inventory too. The builder rejects
unlisted HDL/constraint/IP inputs in the source directories before copying.
`validation/source-import.json` is historical provenance, not the build inventory.
The receipt derives the seed from the actual single QSF assignment.
It also records the SHA-256 of the maintained project inventory. Packaging
requires this identity, the exact current hashed-input set, and matching bytes
for every input. A subset receipt cannot qualify additional or omitted inputs.
Generated caches/IP upgrades stay in build copies.
Outputs are preserved: use `-Output build/fpga-next` for another build, with matching
`--build` arguments when packaging/auditing it, rather than deleting prior results.
@@ -120,10 +141,42 @@ Packaging verifies the RBF and boot/SSC ROM identities, writes a manifest and
SHA256SUMS, and creates a copyable `fat/` overlay. No files from build caches or
source-reference downloads are installed. Packaging requires reviewed changes
committed; corresponding source comes only from that committed Git tree, never
untracked local files. `-PublicPackage` omits all separately obtained/assembled ROMs
untracked local files. Installed notices are also read from committed Git blobs,
so an untracked file in `LICENSES/` is excluded from both archive layers. The
source-review payload uses a maintained path/type allowlist in `tools/release.py`;
historical RBFs, PDFs and Office files remain in full Git history but are omitted
from that payload. `SOURCE-CHECKOUT.txt` records the pinned full-clone build route.
`-PublicPackage` omits all separately obtained/assembled ROMs
and produces a core/source distribution requiring user ROM preparation. It is
distinct from a complete local install package. Details: docs/INSTALL.md.
Legacy fitted receipts without `project_inventory_sha256` are rejected rather
than silently upgraded. Preserve the old build directory, RBF and evidence. The
supported independent qualification route is a fresh `Build-FPGA.ps1 -Output
build/fpga-qualified` run from the pinned checkout, followed by its own functional,
detailed timing and hardware checks appropriate to release acceptance. A
prepare-only comparison establishes input equality; it does not create fit or
timing evidence. Do not add an inventory hash to an old receipt and present it as
newly qualified. Packaging-only changes need not alter RTL, but do not waive this
receipt requirement.
The real local-package guards can target a new qualified build and package
without moving or editing historical evidence. From the checkout in PowerShell:
```powershell
$env:COCO3PLUS_TEST_BUILD = 'build/fpga-audit-receipt'
$env:COCO3PLUS_TEST_RELEASE = 'dist/coco3plus-audit'
python -B tests/test_release_guards.py
```
Paths are resolved relative to the repository root unless absolute. Defaults
remain `build/fpga` and `dist/coco3plus` when the overrides are absent. Missing
actual local artifacts cause explicit skips; these are separate from portable
fixture tests in `tests/test_tooling_guards.py`. A selected complete package must
have the current source inventory, outer ZIP, exact committed source revision,
and committed Greg Miller notice; an existing historical package lacking those
properties is a failure rather than a substitute for checking the new package.
Portable Python entry points under tools/ support native macOS/Linux tooling
where available. Quartus itself has no native macOS build; use the Windows or
supported Linux toolchain. The automatic prebuilt-tool download is Windows x64.