[tony-davis]

Add Optional Enhanced Metadata Fields to Test Categories

This PR adds optional fields to the test_categories.yaml schema to enable richer test documentation and future AI-assisted test selection.

Key Points ✅

• All new fields are optional - Zero burden on teams that don't want them
• 100% backward compatible - Existing YAML files work unchanged
• Minimal code changes - Parser naturally ignores unknown fields (1 comment added for clarity)
• Incremental adoption - Teams add fields only when they see value
• Clear example - Enhanced one category, kept 5 others minimal to show backward compatibility

Changes

1. README.md: Document optional enhancement fields with examples and use cases
2. parse_test_categories.py: Added clarifying comment (no logic changes needed!)
3. test_categories.yaml: Enhanced level1 category as example, kept level2-level6 unchanged

Examples

Minimal usage (works exactly as base PR):

test_categories:
  smoke:
    description: "Quick sanity tests"
    test_patterns: ["*smoke*"]
    labels: ["smoke"]

Enhanced usage (when team wants better documentation):

test_categories:
  smoke:
    description: "Quick sanity tests"
    notes: "Run for any API changes. Critical path tests."
    source_coverage: ["library/src/api.cpp"]
    api_coverage: ["initialize", "cleanup"]
    feature_tags: ["fast", "critical-path"]
    test_patterns: ["*smoke*"]
    labels: ["smoke"]

Why Include Optional Fields in the Standard?

1. Consistency - Teams wanting richer metadata have a standardized structure
2. Flexibility - No mandatory adoption, teams use what they need
3. Prevents divergence - Projects like hipBLASlt that need extra metadata can adopt the standard as-is rather than creating project-specific extensions
4. Future-proof - Enables innovation (AI-assisted test selection, better documentation) without breaking changes

Testing

• ✅ Existing minimal categories (level2-level6) work unchanged
• ✅ Enhanced category (level1) parses correctly
• ✅ Parser gracefully ignores optional fields
• ✅ CTest execution behavior unchanged
• ✅ Backward compatible with existing deployments

Context

This enables projects like hipBLASlt (with ~200+ test configurations) to adopt the standardized approach with rich test metadata, rather than implementing project-specific extensions that would defeat the standardization effort.

[tony-davis]

Quick note on the changes:

parse_test_categories.py: The diff looks larger than it is - I added a 3-line clarifying comment, and then pre-commit hooks (black formatter, trailing whitespace) auto-reformatted the file. No functional changes to the parser logic.

Actual substantive changes:

• README.md: Added optional fields documentation
• test_categories.yaml: Enhanced level1 as example, kept level2-6 minimal
• parse_test_categories.py: Added comment explaining optional fields are preserved but not processed

Everything else is formatting.

[Copilot]

Pull request overview

This PR extends the test_categories.yaml schema with optional metadata fields to support richer test documentation and future AI-assisted test selection capabilities. The enhancement maintains 100% backward compatibility by making all new fields optional and leveraging the YAML parser's natural behavior of ignoring unknown fields.

Changes:

• Enhanced documentation to describe new optional metadata fields (notes, source_coverage, api_coverage, feature_tags, dependencies, llm_context)
• Added clarifying comment in parser explaining that optional fields are preserved but not processed
• Updated code formatting from single quotes to double quotes for consistency
• Demonstrated backward compatibility by enhancing only one test category (level1) while keeping others minimal

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 2 comments.

File	Description
shared/ctest/parse_test_categories.py	Code formatting improvements (single to double quotes) and added comment documenting optional enhancement fields
shared/ctest/README.md	Added comprehensive documentation for optional metadata fields with examples and use cases
projects/hipblas/clients/gtest/test_categories.yaml	Enhanced level1 category with optional metadata as an example; other categories remain minimal to demonstrate backward compatibility

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.