[delphix-devops-bot]

Jira: TOOL-31618 Add a repo-side testing doc to linux-pkg for the bugfix pipeline

Background

This is one of twelve per-repo tickets under TOOL-31503, an initiative to move repo-specific
testing knowledge for the bugfix-pipeline automation out of platform-team-claude-plugins'
shared skills and into each target repo as discoverable documentation, with general rules and
fallbacks staying in the plugin.

Problem

linux-pkg has no repo-side testing documentation an automated bugfix run (or anyone) can read to
learn how to test a change here, or how to use this repo to test a change made in one of the ~39
packages it orchestrates. The README's own "Testing your changes" section is incomplete — its
"Testing changes to an existing package" subsection ends literally TODO: complete section.

Solution

Adds docs/testing.md, an automated-reader-oriented testing doc covering: unit/lint testing of
linux-pkg itself (make shellcheck/make shfmtcheck, already run automatically by this repo's
own .github/workflows/main.yml); building a package (buildpkg.sh); which CI exists for a
package and how it's triggered (the per-package Jenkins pre-push job, query-packages.sh,
package-lists/); deploying a change via appliance-build's combined-packages pipeline, with the
platform's own kernel-module-never-on-the-claude-VM ceiling carried forward; and linux-pkg's own
package-source-override mechanism (buildpkg.sh -g/-b/-r, lib/common.sh's
get_package_config_from_env()) for building/validating a change made in one of its orchestrated
packages.

Cross-repo mechanisms this doc touches but doesn't reproduce (git-ab-pre-push's own resolution
logic, the Jenkins job definitions themselves, the appliance-build pipeline's own mechanics) are
named at the boundary of what linux-pkg itself hands off/consumes, with a pointer to that
mechanism's own repo (git-utils, devops-gate, appliance-build respectively) for its actual
behavior — each of those repos has its own per-repo ticket under the same umbrella.

Adds a new root CLAUDE.md (this repo had none) pointing at the new doc, and a short
cross-reference from the README's existing "Testing your changes" section — the README itself is
untouched beyond that one link, per this doc being a separate, automated-reader-oriented doc set
rather than an extension of the human-oriented README. Adds a short comment next to
lib/common.sh's get_package_config_from_env() noting that a change to that precedence (or to
buildpkg.sh's -g/-b/-r flags) needs docs/testing.md updated.

Testing Done

Current CI runs

Run Type	Status

Prior CI runs

Run Type	Status
validate-the-fix (TOOL-31618) (linux-pkg@4f2c495)	OUT_OF_SCOPE
ab-pre-push build #15493 (linux-pkg@4f2c495)	PASSED

Notes:

• The two prior runs above exercised the first revision of the doc and were not re-run after
  review: the later revisions are documentation-only (plus one comment in lib/common.sh), and
  the style and GitHub Actions checks passed on the final head.
• Full per-run anchors (product/test SHAs, DCenter group, run-config, exact command) are tracked
  in delphix/dlpx-bugfix-notes (tickets/TOOL-31618.md), not duplicated here.

[manoj-joseph]

Reviewed docs/testing.md against buildpkg.sh, the Makefile, the README and git-utils' git-linux-pkg. The lint, workflow, query-packages.sh and package-list content checks out. linux-pkg is not a test-infrastructure repo, so one testing doc is right. The comments below are the problems that would mislead or leave a pipeline stuck: one wrong command, one wrongly named mechanism, and the two things a pipeline most needs (how to run CI for a package change, and how to get it onto a VM) which are deferred instead of stated.

[manoj-joseph]

Minor points that go with my earlier review on this PR. None of these blocks anything.

[manoj-joseph]

One significant finding: the doc misdescribes how CI passes the package branch to buildpkg.sh. Minor items are inline.

[Copilot]

🟡 Changes recommended

The guide needs corrections to source selection, required build prerequisites, and the automation-VM deployment restriction.

3 open issues

• Document required build environment variables · New
• Clarify -r package suffix versus -b source reference · New
• Explicitly prohibit kernel module operations on the automation VM · New

What changed in this PR

Adds repository-local testing guidance for the bugfix pipeline and developers working with linux-pkg.

Changes:

• Documents lint checks, package builds, source overrides, CI, and deployment workflows.
• Adds discovery links and reminders to keep testing guidance current.
• Clarifies configuration precedence in an existing code comment; runtime behavior is unchanged.

File	Description
README.md	Links to the new testing guide.
lib/​common.sh	Clarifies precedence comments and adds a documentation-maintenance reminder.
docs/​testing.md	Adds testing, build, CI, and deployment guidance.
CLAUDE.md	Points automation to testing guidance and maintenance expectations.

_{Review effort: Balanced}

[Copilot]

🟡 Changes recommended

Remaining inaccuracies in validation instructions and CI coverage claims could mislead automated testing.

4 open issues

• Explicitly prohibit kernel module operations on the automation VM
• Clarify -r package suffix versus -b source reference
• Document required build environment variables
• Qualify URL matching coverage for packages with no repository URL · New

_{Review effort: Balanced}

[Copilot]

🔵 Needs a closer look

Cross-repository workflow claims remain unverified, and the testing guidance needs corrections before human approval.

2 open issues

• Qualify CI coverage claims by appliance membership and URL matching · New
• Document packages that ignore source overrides or use prebuilt artifacts · New

4 resolved since last review

• Explicitly prohibit kernel module operations on the automation VM
• Clarify -r package suffix versus -b source reference
• Document required build environment variables
• Qualify URL matching coverage for packages with no repository URL

_{Review effort: Balanced}

[Copilot]

🟢 Approval recommended

The changes are documentation-only, with one nonblocking accuracy correction remaining.

1 open issue

• Hardcoded Git URL incorrectly disables branch override · New

2 resolved since last review

• Document packages that ignore source overrides or use prebuilt artifacts
• Qualify CI coverage claims by appliance membership and URL matching

_{Review effort: Balanced}

[Copilot]

🟢 Approval recommended

The documentation and comment-only changes have no identified blocking issues.

No open issues 🎉

2 resolved since last review

• Document os-upgrade branch fallback and verify repo-HEAD
• Clarify setup.sh reruns in each fresh build container

_{Review effort: Balanced}

[Copilot]

🟡 Changes recommended

The guide can mislead automation into accepting failed formatting checks and requiring unnecessary matching-kernel VMs for build-only validation.

2 open issues

• Document shfmtcheck limitations and direct formatter validation · New
• Separate build validation from matching-kernel runtime testing · New

_{Review effort: Balanced}

[Copilot]

🔵 Needs a closer look

Cross-repository CI and deployment contracts need human confirmation against their authoritative implementations.

2 open issues

• Document retained failed containers before retrying builds · New
• Correct git URL configuration tiers · New

2 resolved since last review

• Separate build validation from matching-kernel runtime testing
• Document shfmtcheck limitations and direct formatter validation

_{Review effort: Balanced}

[Copilot]

🔵 Needs a closer look

The cross-repository Jenkins and git-utils instructions need maintainer verification because their referenced implementations were unavailable during review.

2 open issues

• Correct git URL configuration tiers
• Document retained failed containers before retrying builds

_{Review effort: Balanced}

[Copilot]

🔵 Needs a closer look

Cross-repository CI and deployment instructions still need human confirmation, and the failed-build recovery guidance needs correction.

1 open issue

• Avoid restarting build container and deleting failed workdir · New

2 resolved since last review

• Correct git URL configuration tiers
• Document retained failed containers before retrying builds

_{Review effort: Balanced}

[Copilot]

🔵 Needs a closer look

The cross-repository Jenkins and git-utils procedures need human confirmation because their implementations were unavailable for verification.

No open issues 🎉

1 resolved since last review

• Avoid restarting build container and deleting failed workdir

_{Review effort: Balanced}