DLPX-99863 Add a repo-side testing doc to delphix-platform for the bugfix pipeline

[delphix-devops-bot]

Jira: DLPX-99863 Add a repo-side testing doc to delphix-platform for the bugfix pipeline

Problem

delphix-platform has no repo-side testing documentation: no CLAUDE.md/.claude content, and
README.md has no testing instructions. An automated bugfix pipeline (or any engineer) working
in this repo has no repo-side source to learn how to unit test a change, deploy it to a test VM,
or know which CI runs exist and how to start them — this is one of twelve per-repo tickets under
the TOOL-31503 umbrella, which moves this kind of repo-specific testing knowledge out of shared
tooling and into each repo as documentation.

Solution

Add docs/testing.md, a separate, automated-reader-focused doc set (linking to, not duplicating,
README.md's own build instructions) covering:

• Unit testing — this repo's actual lint/type-check jobs
  (.github/workflows/main.yml: check-shellcheck/check-shfmt/check-pylint/check-yapf/
  check-mypy) and their exact local-reproduction commands, plus the make check no-op gotcha
  (the Makefile declares .PHONY: check but never implements it).
• Deploying a change to a test VM — git linux-pkg build -m <machine> -t <machine>, and why a
  full bootable appliance image instead needs git ab-pre-push.
• CI runs and how to start them — every check this repo's PRs actually see (the two required
  GitHub-app checks, the 5 lint jobs, the 2 Jenkins pre-push checks, the 3 Mend checks), which of
  them actually boot/test an appliance with the change (none of them — only git ab-pre-push
  does), and a pipeline-specific gotcha (delphix-platform has no dedicated branch-deploy
  parameter for automated QA-gate VM sourcing, unlike linux-pkg/dlpx-app-gate/dms-core-gate).

Also adds CLAUDE.md (none existed) with a short pointer to docs/testing.md, and a one-line
docs/testing.md comment next to the job list in .github/workflows/main.yml and next to the
platform list in the Makefile, so a future change to either is nudged to update the doc. A new
check-docs-coverage job (added to the same .github/workflows/main.yml, reusing its existing
shell-job mechanism) fails automatically if a job is ever added there with no backtick-quoted
reference to its name in docs/testing.md.

Testing Done

Current CI runs

Run Type	Status
validate-the-fix (DLPX-99863) (delphix-platform@114da7f)	OUT_OF_SCOPE (scope-work/documentation ticket; Reproduce mode: skip)

Prior CI runs

Run Type	Status
validate-the-fix (DLPX-99863) (delphix-platform@50c59e2)	OUT_OF_SCOPE

Notes:

• Full per-run anchors (product/test SHAs, DCenter group, run-config, exact command) are tracked in delphix/dlpx-bugfix-notes (tickets/DLPX-99863.md), not duplicated here.

Manual Testing

• Test case: the new check-docs-coverage job correctly extracts every job name from .github/workflows/main.yml (including a quoted-key job) and fails when one has no backtick-quoted reference in docs/testing.md.
  How executed: extracted the job's own embedded script via python3 -c "import yaml; ..." and ran it directly against this repo's real files, and against a constructed copy of the workflow with an added quoted, undocumented job.
  Result: passes against the real repo (all 6 job names referenced in the doc); correctly fails with a clear message against the constructed undocumented-job case.
• Test case: every factual claim in docs/testing.md's CI-runs table (which checks are required to merge, what git linux-pkg build -f/-F actually do, what jenkinsci/appliance-build-orchestrator actually runs) matches live repo/GitHub/Jenkins state, not just plausible-sounding prose.
  How executed: compared against gh api repos/delphix/delphix-platform/branches/develop/protection, gh api .../check-runs on this PR's own head commit, the real git-linux-pkg source in /home/delphix/src/git-utils, and the Jenkins wfapi build description for a recent jenkinsci/appliance-build-orchestrator run.
  Result: two inaccuracies found this way were corrected before the content reached its final, filed form.

[Copilot]

🟡 Changes recommended

The local Pylint instructions omit a dependency installed by CI, causing failures in clean environments.

1 open issue

• Add netifaces to local Pylint prerequisites · New

What changed in this PR

Adds repository-local testing guidance for engineers and the automated bugfix pipeline.

Changes:

• Documents local checks, VM deployment, and CI coverage.
• Adds documentation-maintenance pointers.
• Adds a workflow job checking that job names appear in the testing guide.

File	Description
Makefile	Adds a testing-documentation maintenance reminder.
docs/​testing.md	Documents testing, deployment, and CI procedures.
CLAUDE.md	Points automated readers to the testing guide.
.github/​workflows/​main.yml	Adds the documentation-coverage check and maintenance reminder.

_{Review effort: Balanced}

[Copilot]

🔵 Needs a closer look

Deployment instructions and appliance-testing claims need confirmation against external git-utils tooling and Jenkins configuration.

No open issues 🎉

1 resolved since last review

• Add netifaces to local Pylint prerequisites

_{Review effort: Balanced}

[delphix-devops-bot]

Re: the "needs a closer look" summary on this latest review — the doc's deployment (git linux-pkg build) and CI-runs claims were already verified against live sources before filing, not just written from plausible-sounding prose: the git-linux-pkg behavior (what -f/-F actually do) against the real source in git-utils, what jenkinsci/appliance-build-orchestrator actually runs against a recent Jenkins build's own wfapi description, which checks are actually required against gh api repos/delphix/delphix-platform/branches/develop/protection, and the full current check-run list against this PR's own check-runs (see the "Testing Done" section of this PR's description for the specifics). No concrete inaccuracy was named in this review beyond the one already fixed (netifaces), so marking this settled.

[manoj-joseph]

Findings on the testing doc: skill and PR-number citations, a dead link, narration of how the doc was verified, and an unsupported claim. Minor items are inline too.

[delphix-devops-bot]

Addressed every item from the latest review (50c59e2): removed the Claude skill/plugin citation and the specific PR-number citations, replaced the dead git-utils doc link with a pointer to the repo itself (plus git ab-pre-push --help until that doc exists), rewrote the sections that narrated how this doc was verified to instead state what each check does and how to read its result, and corrected the get_linux_pkg_package() claim to cite the actual source (_get_params_for_extra_repo() in src/git_utils/lib/appliance_build_job.py). Also applied the three minor items (plain wording in the intro, defaults coming from the Jenkins job, and the aws/esx non-ZFS test restriction). Replied on each inline thread with the specific fix and resolved them.

[Copilot]

🔵 Needs a closer look

Deployment and CI guidance depends on external tooling and service settings that still need independent confirmation.

No open issues 🎉

_{Review effort: Balanced}

[manoj-joseph]

One significant finding on the new head: the branch-parameter claim contradicts git-utils.

[Copilot]

🟢 Approval recommended

No unresolved issues remain, and focused verification supports the new documentation coverage check.

No open issues 🎉

_{Review effort: Balanced}