/update-libcontainer

name: update-libcontainer
description: Reimport Native Image's vendored libcontainer from a newer JDK while preserving local adaptations in a reviewable commit stack. Use when performing a full libcontainer update, replaying Native Image changes onto new upstream sources, resolving reimport conflicts, or reviewing such an update.

Update libcontainer

Read the Canonical Instructions

From the repository root, read _substratevm/src/com.oracle.svm.native.libcontainer/README.md_ completely before changing files. Follow its full-reimport, provenance, namespace, and testing instructions. Use this skill only for the additional history and conflict-resolution rules below.

Establish the Previous Full-Import Baseline

Do not treat the current `@BasedOnJDKFile` annotations as authoritative import revisions. Annotations may have been advanced without a full reimport to keep change-detection gates passing while the actual import was deferred.

Before changing the vendored sources:

1. List all current annotation revisions and identify the lowest revision in upstream commit chronology. Use it only as a candidate for the previous full-import revision; do not choose it by lexical tag ordering. 2. Inspect the Git history of the imported libcontainer files and find the most recent full-import stack. Distinguish a broad full import from annotation-only updates and focused adoptions of individual upstream changes. 3. Determine the JDK revision used by that full import. If it matches the lowest annotation candidate, treat the match as strong evidence. If it does not, stop and investigate older history rather than guessing. 4. Check out that exact old JDK revision from the same upstream repository that will supply the new revision. 5. In a temporary clean Graal worktree at the pre-update commit, remove the namespace with `mx svm_libcontainer_namespace remove` and save the resulting old adapted source tree. 6. In that temporary worktree, run `mx reimport-libcontainer-files --jdk-repo <old-jdk-checkout>` using the verified candidate revision. 7. Compare the reimported old JDK files with the saved namespace-free adapted tree. The differences must be limited to recognizable Native Image adaptations such as `NATIVE_IMAGE` guards, minimal local replacements, reduced dependencies, and required header or license normalization.

If the verification diff contains unrelated upstream implementation changes, the candidate is not a valid merge base. Repeat the history investigation with an earlier candidate; do not begin the update until reimporting the old revision reproduces the vendored tree modulo Native Image adaptations.

Record the verified old full-import revision, its upstream repository URL, the supporting full-import commit, and the saved pristine old source tree. Use this verified pristine tree as the merge base for all imported files.

Preserve a Reviewable History

Record the upstream repository URL and the verified old and new JDK revisions before starting. Do not mix Oracle JDK, OpenJDK, or labs-openjdk sources unless their equivalence for the imported files has been verified and documented. Keep each mechanical transformation separate from judgment-heavy changes, in this order:

1. Remove the libcontainer namespace, commit only that transformation, and record the commit as the previous adapted source commit. 2. Reimport the new JDK files and commit the unadapted upstream snapshot. 3. Replay the previous Native Image adaptations with a three-way merge and commit the result, including conflict markers. 4. Resolve every conflict in a separate, immediately following commit. 5. Review newly imported code for Native Image reachability and commit any exclusions as a focused semantic change. 6. Materialize the previous effective Native Image sources in a generated review-only commit. 7. Replace them with the new effective Native Image sources in the primary semantic review commit. 8. Restore the canonical guarded sources in a generated review-only commit. 9. Restore the namespace and commit only that transformation. 10. Update `@BasedOnJDKFile` provenance in a separate commit. 11. Put build integration or other follow-up changes in focused commits after the reimport stack.

Do not squash the marker-bearing commit into its resolution. The intermediate commit is deliberately not buildable; it records the exact overlap between the old adaptations and the new upstream sources for review. The resolution commit must be adjacent so no final branch state retains unresolved markers.

Replay Adaptations with Diff3

For each imported file, treat these versions as the three-way merge inputs:

• ours: the old Native Image-adapted file after namespace removal
• base: the matching file from the verified previous full-import JDK tree
• theirs: the file from the new JDK revision

Use diff3-style markers and descriptive labels, for example:

git merge-file -p --diff3 \
  -L "Native Image adaptations" \
  -L "$old_jdk_revision" \
  -L "$new_jdk_revision" \
  "$old_adapted_file" "$old_jdk_file" "$new_jdk_file" > "$vendored_file"

Apply the resulting files on top of the unadapted reimport commit. Commit both cleanly merged adaptations and marker-bearing files together before resolving conflicts.

Inspect the replay as two separate diffs:

• old adapted tree to replayed tree: must retain the relevant upstream update
• unadapted new reimport to replayed tree: must contain only Native Image adaptations and explicit conflict resolutions

If the upstream reimport changed imported files but the replayed tree equals the old adapted tree, stop. The merge base or replay procedure is wrong; do not continue with provenance updates, projections, or validation of that tree.

Resolve Conflicts Deliberately

Review all three sides of every conflict. Preserve relevant upstream changes and re-establish Native Image behavior, including `NATIVE_IMAGE` guards, local replacements, reduced dependencies, and deliberat