[Code Quality] Clarify timeout-minutes vs timeout_minutes naming convention

[github-actions]

Description

The workflow schema contains both timeout-minutes and timeout_minutes as separate top-level properties, creating confusion about which form to use.

Evidence

jq '.properties | keys[]' main_workflow_schema.json | grep timeout
timeout-minutes
timeout_minutes

Questions to Answer

1. Are both intentionally supported for YAML naming compatibility?
2. Is one form deprecated in favor of the other?
3. Does the parser handle both equivalently?
4. Which form should documentation recommend?

Analysis Needed

Check the parser:

grep -r "timeout.minutes\|timeout_minutes" pkg/workflow/ pkg/parser/

Check documentation:

grep -r "timeout-minutes\|timeout_minutes" docs/

Check production usage:

grep -r "timeout[-_]minutes" .github/workflows/*.md

Suggested Resolution

After investigation, document one of these approaches:

Option 1: Both Supported (YAML Flexibility)

### Timeout (`timeout-minutes:` or `timeout_minutes:`)

Both hyphenated and underscored forms are supported for YAML compatibility:

``````yaml
timeout-minutes: 30  # Preferred
timeout_minutes: 30  # Also supported

Recommendation: Use timeout-minutes (hyphenated) to match GitHub Actions conventions.

### Option 2: One Deprecated
``````markdown
### Timeout (`timeout-minutes:`)

⚠️ **Note**: The `timeout_minutes` field is deprecated. Use `timeout-minutes` instead.

Files Affected

• docs/src/content/docs/reference/frontmatter.md (clarification)
• pkg/parser/schemas/main_workflow_schema.json (potentially mark one as deprecated)

Success Criteria

• Users know which form to use
• Documentation clearly states naming convention policy
• Schema deprecation notes (if applicable)
• No breaking changes to existing workflows

Source

Extracted from Schema Consistency Audit discussion #13424 - identified as Low Severity schema clarity issue.

Priority

Low - Documentation clarity improvement (not blocking, but reduces confusion)

AI generated by Discussion Task Miner - Code Quality Improvement Agent

• expires on Feb 17, 2026, 9:11 AM UTC