Centralized repository for HyperShift test plans and pre-merge verification reports. Replaces the previous pattern of self-hosting these artifacts in individual personal GitHub repositories.
.
├── plans/ # Test plans (Markdown; IEEE 829 or lightweight)
│ ├── <jira-key>.md # Plan linked to a Jira issue (e.g. ocpstrat-3298.md)
│ └── <slug>.md # Plan without a Jira issue (e.g. csi-snapshot-validation.md)
├── reports/ # Verification reports (HTML bundle or Markdown)
│ └── <jira-key>/ # Reports grouped by Jira issue
│ ├── metadata.yaml # Required report metadata
│ ├── index.html # HTML bundle entry-point (preferred format)
│ ├── scenario-N.html # Per-scenario detail pages
│ ├── appendices.html # Supplementary evidence
│ ├── automated-tests.html # CI / automated-test results
│ ├── assets/ # Screenshots, diagrams
│ ├── scripts/ # Helper scripts used in testing
│ ├── derived/ # Optional IEEE 829 Markdown derived from HTML
│ │ └── report.md
│ └── <pr-number>.md # OR: lightweight Markdown report per PR
├── docs/ # Repository documentation
│ ├── format.md # Metadata model, format specification, relationships
│ └── migration.md # Migration guide and inventory
├── AGENTS.md # Non-negotiable rules for AI agents
├── CONTRIBUTING.md # How to add plans and reports
└── README.md # This file
Each test plan is a single Markdown file with YAML front-matter metadata. Plans support two profiles:
- IEEE 829 — set
ieee_829: truein front-matter to follow the full IEEE 829-2008 body structure with numbered sections. Preferred for comprehensive, multi-scenario plans. - Lightweight — when
ieee_829is absent orfalse, a simpler free-form Markdown structure covering scope, test cases, and acceptance criteria is valid.
A single plan can reference multiple Jira issues and PRs to support backport workflows. See docs/format.md for naming conventions and the metadata model.
Verification reports capture the results of executing a test plan against a specific PR. Reports are grouped into subdirectories named by Jira issue key.
Reports support two formats:
- HTML bundle (preferred) — a self-contained directory with
index.html, per-scenario pages (scenario-N.html), appendices, automated-test results, images, and helper scripts. This is the existing format used by OCPBUGS and CNTRLPLANE verification reports. - Markdown — a lightweight single-file report (
<pr-number>.md) following the template in docs/format.md.
Format policy: HTML bundles are stored as-is; they must not be converted to Markdown during migration. An IEEE 829 Markdown summary may optionally be derived from an HTML bundle (placed in
derived/report.md), but derivation must not replace or discard the original HTML.
- docs/format.md — Metadata model, naming conventions, format specification, and relationship model (1-to-N Jira/PR support).
- docs/migration.md — Guide for migrating existing test plans from personal repositories, including a migration inventory.
- Read the contribution guide.
- Review the format specification for metadata requirements.
- Copy an existing plan from
plans/or use the template in docs/format.md. - Open a PR adding your plan or report.
This repository is designed for integration with
Chai Bot and the ai-helpers
skill library. The target workflow:
@chai-bot make a test plan for JIRA-1234 and add it to test-results-verification
See docs/format.md for the integration contract that automation must follow when generating or updating plans.
Status: Automation integration is tracked in CNTRLPLANE-4323. The contract is documented; implementation in the
ai-helpersskill library is a follow-up.
- openshift/hypershift — main HyperShift repository
- Jira: CNTRLPLANE-4323 — tracking issue for this repository's structure