Cnuas, Version Pinning Policy¶

Summary¶

This project depends on two large external repositories:

Submodule	Path	Source
Linux kernel	`linux/`	`PacketFive/linux` (fork of `torvalds/linux`)
QEMU	`qemu/`	`PacketFive/qemu` (fork of `qemu/qemu`)

Both are pinned to specific commits that the kernel modules and vNIC device have been built and tested against. Never run git submodule update --remote, it will move pointers off the tested versions.

Currently Pinned Versions¶

Submodule	Tag	Commit
`linux`	`v6.19`	`05f7e89ab973`
`qemu`	`hicain-v0.1.0`	`507169f516`

How Submodule Pinning Works¶

A git submodule is pinned to a specific commit SHA, not a branch or tag. When you commit the parent repo, the submodule's exact SHA is recorded.

Cloning fresh (gets exact pinned versions)¶

git clone --recursive git@github.com:PacketFive/vdc.git
# OR
git clone git@github.com:PacketFive/vdc.git
cd vdc
git submodule update --init --recursive

This always checks out the exact pinned SHAs, guaranteed.

Verifying pinned versions¶

cd vdc
scripts/verify-versions.sh

Updating to a new pinned version (intentional)¶

When you need to bump kernel or QEMU version:

# Update submodule
cd linux
git fetch origin
git checkout v6.20      # or new commit
cd ..

# Test thoroughly
./build_and_test.sh

# Commit the new SHA
git add linux
git commit -m "Bump linux submodule to v6.20"
git push

What NOT to do¶

❌ Never	✅ Instead
`git submodule update --remote`	`git submodule update --init`
Add `branch = master` to `.gitmodules`	Leave it out, pin to commit
Manually `cd linux && git pull` without committing the new SHA	Always commit the parent repo after updates

Tag Naming Convention¶

Pattern	Use
`hicain-vMAJOR.MINOR.PATCH`	Marks tested versions of QEMU fork
`v6.X`	Linux kernel, use upstream tags

Why Not Just `branch = master`?¶

Setting branch = master in .gitmodules enables git submodule update --remote, which silently moves submodule pointers to upstream HEAD on each invocation. This is dangerous for kernel and QEMU because:

Kernel APIs change between minor versions (our modules target 6.19 specifically)
QEMU device APIs change frequently (we hit this with Property array, class_init signature)
A surprise upstream change can break the entire build

Pinning to commits + explicit version bumps via PR is the safe approach.