Updating a kernel
Use this process to add a selectable kernel version or update the stable or unstable selection. It preserves the complete downstream behavior shipped by the predecessor, including pristine backports and package-layer patches. The update-kernel skill routes agents here. Read the downstream patch-series policy before changing the stack.
Keep exact revisions, generated inventories, conflict decisions and check results in the existing Markdown release or session tracker. Derive the patch inventory from the selected source range on every run.
Establish the source and target
Record the requested upstream version, stable/unstable role, and whether the
request adds a version only or replaces that role's selection. For a replacement,
start from the role's current selector in os/packages/linux/available-kernels.nix.
For another kernel line or an add-only request, inspect the applicable catalog
entries and upstream ancestry to identify the latest applicable packaged
predecessor. Explain that choice; do not substitute the highest version across
unrelated lines, a branch tip, subject prefix or commit date. If the requested predecessor differs
from current packaging, resolve that difference before replaying.
Inspect these source interfaces together:
os/packages/linux/available-kernels.nix: selectors, immutable Linux revision and hash, per-version features/configuration, post-config patches and ZFS pairing.os/packages/linux/packages.nix,default.nix,generic.nix, andos/modules/config/kernel.nix: source fetching, common/version-conditional patches, configuration, built-in/external ZFS and module construction.os/packages/zfs/: paired ZFS source, package patches and build interfaces.flake.nixand.github/workflows/kernels.yml: available versions, generated CI closures and actual workflow triggers.
Record the predecessor's complete catalog entry and effective package layers. Do not assume every catalog field reaches every builder; trace the actual selected path. A patch outside the Linux Git range still needs an explicit preservation or compatibility decision.
Use the packaged Linux revision as old_head. Resolve the matching upstream
release as old_base and the requested release as new_base from authoritative
upstream release history. Discover tag and peeled commit identities with
git ls-remote and fetch the exact required refs deliberately. Check each source
Makefile's version and ancestry. A stale downstream maintenance branch is not
authoritative when the package pins another head.
In a partial clone, keep lazy fetching disabled throughout inspection, replay and continuation in the owned shell:
export GIT_NO_LAZY_FETCH=1
git cat-file -e "$old_head^{commit}"
Missing objects call for a deliberate fetch, not an accidental large promisor download. Record the exact upstream tag objects and peeled commits after acquisition.
In the Linux checkout, with the three verified commit IDs assigned:
git merge-base --is-ancestor "$old_base" "$old_head"
git log --reverse --format='%H %s' "$old_base..$old_head"
git rev-list --count "$old_base..$old_head"
git rev-list --merges "$old_base..$old_head"
Save the full generated inventory before replay. Inspect every commit in the
range, including generic fixes without [vpsAdminOS]. Investigate merges and
unexpected ancestry before choosing the replay shape. If reconstruction is
needed, prove that history-only step against the original before mixing in the
version port.
Replay and resolve the whole stack
Preserve old_head in an exact dated local backup ref before rewriting. Retain
published refs and use an owned isolated topic branch/worktree starting at that
head. Follow the active repository/workspace branch and hook rules.
For a verified linear range, from that topic branch:
git -c rerere.enabled=false rebase --no-update-refs \
--reapply-cherry-picks --empty=stop --onto "$new_base" "$old_base"
This keeps already-empty commits by default and stops when a replay becomes empty. Inspect intentional empty commits and account for their disposition. For a history containing merges, inspect dependencies and choose a replay that preserves their meaning rather than blindly flattening it with this example. Disable automatic rerere reuse, as above, or inspect every reused resolution.
If a replay stalls while classifying objects in a partial clone, distinguish
classification overhead from missing content. Stop and join only the owned
command, then reconcile HEAD, index and rebase done/todo against the saved
inventory before continuing: an interrupt can consume a todo entry before its
commit is created. Check that the required parent, old and current blobs are
available locally.
When that evidence identifies expensive promisor classification, try command-local
-c remote.NAME.promisor=false for each configured promisor remote on the
continuation, keeping GIT_NO_LAZY_FETCH=1. Substitute the actual remote names;
do not change stored clone configuration. Apply this remedy only after diagnosis.
Keep missing-content errors visible and acquire any missing objects deliberately
before proceeding.
For each conflict, read the old logical patch, the upstream change, surrounding callers and relevant ordering, locking and lifetime rules. Preserve both the upstream fix and downstream behavior. Resolve every conflict semantically; wholesale ours/theirs selection or skipping a patch to evade a conflict is not a resolution. A clean application also needs semantic review.
Record the paths, colliding changes, chosen resolution and focused checks under the old logical owner. Fold caused compatibility repairs into that owner. Follow the patch-series policy for identity, truthful provenance, authorship, patch versions and chronological development history. A substantive adaptation advances the logical patch version; an unchanged transplant does not need an artificial version bump. Preserve independent generic fixes as independent logical patches.
Account for every old patch
After replay, capture new_head and compare the complete ranges:
git log --reverse --format='%H %s' "$new_base..$new_head"
git range-diff "$old_base..$old_head" "$new_base..$new_head"
git diff --check "$new_base..$new_head"
Maintain one Markdown row per old logical commit in the existing tracker:
| Old commit | New commit or exact upstream equivalent | Disposition | Rationale and evidence |
|---|---|---|---|
Use unchanged, adapted or upstreamed dispositions. Review the actual patches and final tree as well as the range-diff. Use counts and patch IDs to find discrepancies, then inspect the source to verify behavior. Investigate every omitted, extra, empty, changed or rerere-resolved patch; account for new prerequisites too.
An upstreamed disposition requires the exact upstream equivalent, ancestry showing it is included in the target, and source/effect evidence that it preserves the old intent. Only then omit a redundant replay. Raise intentional behavior removal as a scope decision instead of labelling it upstreamed. Reconcile the package-layer patch/configuration/ZFS inventory as well as the Git range.
Finish logical ownership, dependency order, messages and provenance. Remove fixup/WIP residue and search changed files for conflict markers. Capture direct review and focused checks for adapted code. Diagnose and fix build failures while preserving every carried patch and its behavior before declaring the update ready.
Publish the final source and register it
A dated preparation branch may publish the candidate through the authorized
feature workflow so its immutable archive is available for review and product
checks. Keep that branch and the backup refs available for recovery. After the
patch-series policy's review and exact-head validation gates pass, publish the
verified Linux head on vpsadminos-<upstream-version>. Do not
merge the stack into Linux's default branch or a series branch, or update a
floating series alias such as vpsadminos-6.12 without direction.
Before publication, inspect the exact version branch:
version_branch="vpsadminos-$target_version"
git ls-remote --heads origin "refs/heads/$version_branch"
If it already points to new_head, the version branch is already published.
If absent, publish with git push origin "$new_head:refs/heads/$version_branch" under the task's
source-publication authorization. Read the exact remote ref again and require
its full SHA to equal new_head. If it points elsewhere, preserve it and inspect
why; do not force-update or repoint it to finish the task. For an intentional
later downstream revision on the same upstream version, the existing -2, -3
branch convention may be used when needed after checking current refs.
Do not create downstream release tags automatically. Reading and verifying upstream release tags remains part of source discovery. Record the canonical remote, full version-branch ref, freshly verified remote SHA, final tested Linux SHA and consuming OS catalog revision/hash in the existing tracker.
The Linux builder uses fetchurl, so hash the GitHub archive bytes, not an
unpacked NAR or source tree. For the published candidate or final new_head:
archive_url="https://github.com/vpsfreecz/linux/archive/$new_head.tar.gz"
nix store prefetch-file --json "$archive_url"
Use the returned hash for the new catalog entry and realize the actual package
source to confirm it. Do not use --unpack. A changed final source head requires
a new archive hash; keep a single final pin rather than intermediate repins.
Add the target entry to os/packages/linux/available-kernels.nix, carrying the
predecessor's compatible configuration, features, package patches and ZFS
revision/hash/patches. Inspect upstream compatibility before changing any layer.
Check version-conditional patches and all builder paths explicitly; do not merely
copy fields and assume they apply.
For a role replacement, set stableKernelVersion or unstableKernelVersion to
the target and verify the resolved selection below. For add-only work, state
that the selectors remain unchanged and evaluate an explicit target selection
as well. Retain old entries and their immutable identities. Pruning or replacing
an existing entry requires a separate decision covering explicit pins,
livepatch targets, reproducibility and recovery.
Verify the selected product
Enter the repository's nix develop environment. Enumerate the catalog with
nix eval --json .#lib.kernelVersions. Evaluate both role defaults and the actual
package sources; this example uses the normal QEMU configuration:
nix eval --json --impure --expr '
let
f = builtins.getFlake (toString ./.);
inspect = unstable:
let
c = (f.lib.vpsadminosSystem {
system = builtins.currentSystem;
modules = [ ./os/configs/qemu.nix {
system.vpsadminos.enableUnstable = unstable;
} ];
}).config;
in {
selected = c.boot.kernelVersion;
linuxVersion = c.boot.kernelPackage.version;
linuxSource = toString c.boot.kernelPackage.src;
linuxDrv = c.boot.kernelPackage.drvPath;
zfsUserSource = toString c.boot.zfsUserPackage.src;
zfsBuiltinSource = toString c.boot.zfsBuiltinPkg.src;
};
in { stable = inspect false; unstable = inspect true; }
'
Compare the selected entry's revision/hash with the evaluated source derivation
and its URL/hash inputs. Check the requested role resolves to the target and the
other role and retained entries remain unchanged. For add-only or explicit-pin
checks, add { boot.kernelVersion = "TARGET"; } to the evaluated modules with
the actual target substituted. Evaluate built-in and external ZFS paths where
affected, and inspect their actual package patches and source identities.
Realize only c.boot.kernelPackage.src from the same system expression with
nix build --no-link --impure --expr to verify the fixed-output archive without
starting compilation. Preserve the source path/derivation and relevant flake
inputs. Run Nix formatting and required hooks. For process changes, validate the
skill using skill-creator's quick_validate.py, inspect metadata, links and
examples, and run make doc in the declared environment.
Review all intended final commits, the complete Linux ranges/correspondence and OS diff under the active independent-review rules before long product checks. Include package-layer decisions, documentation placement, exact source pins and history/migration provenance in that review.
The kernel workflow derives its matrix from all catalog keys. Its triggers are
specified in .github/workflows/kernels.yml; an ordinary feature-branch push
does not itself trigger the kernel build. Evaluate the generated target output,
then build the exact pinned closure using the existing entry point:
kernel_output_version=$(printf '%s' "$target_version" | tr '.-' '__')
nix eval --raw ".#ci-toplevel-kernel-$kernel_output_version.drvPath"
make OUTPUT="ci-toplevel-kernel-$kernel_output_version" toplevel
This closure includes the kernel dev and builtins-config dev outputs needed by subsequent consumers. Use the binary cache and diagnose a miss before accepting an unexpected local kernel build. Local compilation is expected when intentionally changing kernel sources/configuration or when the responsible runner has not published that derivation; record the reason. Monitor long checks under the active environment's verification procedure and avoid redundant builds.
Select existing focused VM tests with ./test-runner.sh ls '<pattern>', then
run them with ./test-runner.sh test <pattern>. Check their evaluated guest
kernel and assert actual booted release/source identity. Stable/unstable overrides
and explicit pins can make a green test irrelevant to this target. Choose
coverage for adapted behavior, boot/module loading, and affected built-in/external
ZFS modes using testing; do not silently retarget unrelated tests.
Record exact heads, inputs, outputs, results and checks that remain unrun.
Compatibility and recovery
Assess each update's kernel/userspace interfaces, external modules, ZFS pairing, persisted formats and mixed-version behavior. A version bump does not establish compatibility by itself. Rebuild external modules against the new kernel; do not reuse the old module directory or build identity. Existing livepatches remain bound to their exact target identity and need their own qualification process.
In an interrupted replay, preserve uncertain edits before repair. git rebase
--abort in the owned worktree returns to the saved start; the backup ref remains
available. Do not reset shared or peer worktrees. Source/hash or product failures
must be diagnosed and corrected before claiming readiness.
Keep old catalog entries and OS generations for recovery. Deployment is a separate authorized operation: prepare the exact paired closure, choose rollout ordering and reboot requirements, and verify effects incrementally. Record when mixed versions are supported or a coordinated update is necessary. Old generations are a rollback path only while new persisted state and ZFS pool features remain compatible; do not enable new pool features as part of a kernel-only update.
The reviewed and verified version branch completes Linux source publication. The OS catalog continues to pin the full immutable Linux commit and archive-byte hash, never the moving branch name. OS integration and other repositories retain their own explicit approval, final-head review and check requirements. Deployment is a separate action. Tune this process from demonstrated execution gaps and keep individual run results in the tracker.