[Schema Consistency] Schema Consistency Check: Deprecation & Migration Path Analysis (Nov 3, 2025)

[github-actions[bot]]

🔍 Schema Consistency Check - November 3, 2025

Executive Summary

This analysis employed Strategy 012: Deprecation & Migration Path Completeness Audit - a novel approach examining how deprecated features are documented, migrated, and communicated. Unlike previous strategies that focused on current schema-code-docs alignment, this strategy analyzes the temporal dimension of schema evolution.

Key Finding: While 100% of workflows have migrated from deprecated features, documentation and warning consistency varies dramatically between deprecations - from gold-standard (stop-time) to completely undocumented (safe-jobs).

Overview

The repository manages deprecations through three mechanisms: hard errors (stop-time), warnings (@import/@include), and silent backwards compatibility (safe-jobs). Analysis of 101 production workflows shows complete migration, but inconsistent communication creates confusion about which features are deprecated and how to migrate.

The stop-time deprecation demonstrates best practices with clear error messages, migration examples, and comprehensive documentation. However, safe-jobs silently accepts deprecated syntax without warnings, and import syntax deprecation lacks migration guides despite functioning warning messages.

Full Consistency Analysis

Deprecation Analysis Summary

Deprecated Features Identified: 5 total

• User-Facing: 3 (stop-time, safe-jobs, @import/@include)
• Internal API: 2 (DefaultGitHubTools, HasNetworkPermissions)

Migration Status: ✅ 100% Complete

• 0/101 workflows use stop-time
• 0/101 workflows use safe-jobs at top level
• 0/101 workflows use @import/@include syntax

Documentation Coverage: ⚠️ 33%

• stop-time: ✅ Fully documented with migration guide
• safe-jobs: ❌ No migration documentation
• @import/@include: ⚠️ Partial (new syntax shown, old not mentioned)

Critical Findings

1. Inconsistent Deprecation Communication Strategy

Issue: Three different deprecation approaches with no consistent policy

stop-time → stop-after (GOLD STANDARD ⭐)

Location: pkg/workflow/compiler.go:594-596

// Check for deprecated stop-time usage at root level BEFORE schema validation
if stopTimeValue, exists := frontmatter["stop-time"].(string); exists {
    return nil, fmt.Errorf("'stop-time' is no longer supported at the root level. Please move it under the 'on:' section and rename to 'stop-after:'.\n\nExample:\n---\non:\n  schedule:\n    - cron: \"0 9 * * 1\"\n  stop-after: \"%s\"\n---", stopTimeValue)
}

Documentation: docs/troubleshooting/errors.md:686-733

• Comprehensive error reference entry
• Multiple examples showing correct syntax
• Explains conversion (minutes → hours, maximums, etc.)
• Error message includes original value for easy migration

Why This Is Excellent:

• Hard error prevents accidental usage
• Error message is a complete migration guide
• Preserves user's value in error message
• Documentation searchable and comprehensive
• Tests verify deprecation enforcement

safe-jobs → safe-outputs.jobs (SILENT FALLBACK ⚠️)

Location: pkg/workflow/safe_jobs.go:331-360

// extractSafeJobsFromFrontmatter extracts safe-jobs section from frontmatter map
// First checks the new location under safe-outputs.jobs, then falls back to old location safe-jobs (for backwards compatibility during transition)
func extractSafeJobsFromFrontmatter(frontmatter map[string]any) map[string]*SafeJobConfig {
    // Check new location: safe-outputs.jobs
    if safeOutputs, exists := frontmatter["safe-outputs"]; exists {
        if safeOutputsMap, ok := safeOutputs.(map[string]any); ok {
            if jobs, exists := safeOutputsMap["jobs"]; exists {
                // ... parse new location
            }
        }
    }

    // Fallback to old location: safe-jobs (for backwards compatibility)
    safeJobs, exists := frontmatter["safe-jobs"]
    if !exists {
        return make(map[string]*SafeJobConfig)
    }
    // ... parse old location
}

Documentation: ❌ NONE

• No error message
• No warning message
• No migration guide in docs
• No mention in errors.md
• Schema doesn't mark field as deprecated

Why This Is Problematic:

• Users don't know safe-jobs is deprecated
• No timeline for removing backwards compatibility
• Silent acceptance creates technical debt
• Future removal will surprise users
• No incentive to migrate

@import/@include → {{#import}} (WARNING ONLY ⚠️)

Location: pkg/parser/frontmatter.go:681-693

// Emit deprecation warning for legacy syntax
if directive.IsLegacy {
    optionalMarker := ""
    if directive.IsOptional {
        optionalMarker = "?"
    }
    fmt.Fprintln(os.Stderr, console.FormatWarningMessage(fmt.Sprintf("Deprecated syntax: %q. Use {{#import%s %s}} instead.",
        directive.Original,
        optionalMarker,
        directive.Path)))
}

Documentation: ⚠️ Partial

• imports.md shows new {{#import}} syntax
• Does NOT mention @import/@include exists
• No migration guide or comparison
• No explanation of why syntax changed

Why This Is Partial:

• Warning message shows exact replacement ✅
• But docs don't acknowledge old syntax exists ❌
• No migration timeline communicated ❌
• Warning goes to stderr (might be missed) ⚠️

2. Schema Lacks Deprecation Markers

Issue: JSON Schema supports deprecated: true but it's unused

Current State:

$ grep -i "deprecated" pkg/parser/schemas/*.json
# No results - zero deprecated field annotations

JSON Schema Specification (draft-07) supports:

{
  "properties": {
    "safe-jobs": {
      "type": "object",
      "deprecated": true,
      "description": "DEPRECATED: Use safe-outputs.jobs instead. This field will be removed in v2.0.0"
    }
  }
}

Benefits of Using Schema Deprecation:

• IDEs show deprecation warnings with strikethroughs
• Schema validation can emit deprecation warnings
• Self-documenting schema
• Tooling can detect deprecated field usage
• Clear removal timeline

3. Missing Deprecation Policy Document

Issue: No documented policy for how deprecations are managed

Should Include:

• Announcement Process: How/where deprecations are announced (CHANGELOG, docs, etc.)
• Migration Window: Standard timeframe before removal (e.g., 3 months, 6 months)
• Backwards Compatibility: When to use errors vs warnings vs silent compat
• Version Semantics: Major vs minor version implications
• Communication: How to notify users (warnings, docs, release notes)
• Removal Process: Testing requirements before removing deprecated features

Suggested Location: docs/src/content/docs/contributing/deprecation-policy.md

Detailed Findings by Category

Documentation Gaps Summary

Feature	Error Docs	Migration Guide	Schema Marked	Warning/Error
stop-time → stop-after	✅ errors.md	✅ In error msg	✅ Removed	Hard Error
safe-jobs → safe-outputs.jobs	❌ None	❌ None	❌ No	Silent
@import → {{#import}}	❌ None	❌ None	N/A	Warning

Production Workflow Analysis

Total Workflows Analyzed: 101

Deprecated Feature Usage:

$ grep -l "^stop-time:" .github/workflows/*.md | wc -l
0  # ✅ No workflows use deprecated stop-time

$ grep -l "^safe-jobs:" .github/workflows/*.md | wc -l
0  # ✅ No workflows use old safe-jobs location

$ grep -l "`@import`\|`@include`" .github/workflows/*.md | wc -l
0  # ✅ No workflows use legacy import syntax

Finding: 100% migration complete despite inconsistent communication

Recommendations

HIGH Priority (Address in next release)

1. Add Deprecation Warning for safe-jobs Backwards Compatibility

File: pkg/workflow/safe_jobs.go:347-348

Change: Emit deprecation warning when old location is used

Impact: Users will be notified to migrate before breaking change

2. Document safe-jobs Migration in errors.md

File: docs/src/content/docs/troubleshooting/errors.md

Add comprehensive error entry similar to stop-time deprecation

3. Mark Deprecated Fields in Schema

File: pkg/parser/schemas/main_workflow_schema.json

Add to safe-jobs property:

"safe-jobs": {
  "type": "object",
  "deprecated": true,
  "description": "DEPRECATED: Use safe-outputs.jobs instead. Will be removed in v2.0.0.",
  ...
}

MEDIUM Priority

4. Create Deprecation Policy Document

File: docs/src/content/docs/contributing/deprecation-policy.md

Define standard process for announcements, migration windows, and removals

5. Add Import Syntax Migration Note

File: docs/src/content/docs/reference/imports.md

Add callout explaining old @import/@include syntax and migration to {{#import}}

Positive Findings

✅ Excellent Migration Success

• 100% of production workflows migrated from all deprecated features
• Zero workflows using any deprecated syntax
• This demonstrates successful internal coordination

✅ Gold Standard Error Handling

• stop-time deprecation is exemplary
• Error message includes migration example
• User's value preserved in error for easy copy-paste
• Comprehensive documentation in errors.md

✅ Thoughtful Backwards Compatibility

• safe-jobs supports old location gracefully
• No workflows broken during migration
• Compiler handles both locations cleanly

Metrics

Metric	Value	Status
Deprecated Features	5 total	3 user-facing, 2 internal
Migration Completion	100%	✅ All workflows migrated
Documentation Coverage	33%	⚠️ 1/3 user-facing documented
Schema Deprecation Markers	0%	❌ None used
Error Message Quality	33%	✅ stop-time excellent, others missing

Implementation Checklist

• Add deprecation warning for safe-jobs backwards compatibility
• Document safe-jobs migration in errors.md
• Mark deprecated fields in JSON schema
• Create deprecation policy document
• Add import syntax migration note to docs
• Review CHANGELOG for deprecation section
• Consider timeline for removing safe-jobs backwards compat

---

Strategy Evaluation

Strategy Used: 012 - Deprecation & Migration Path Completeness Audit (NEW)
Effectiveness: Very High
Findings Count: 6 major findings
Should Reuse: Yes - Every 6-8 analyses

Why This Strategy Is Effective:

• Reveals temporal dimension of schema evolution
• Finds documentation gaps invisible to point-in-time analysis
• Discovers inconsistent deprecation strategies
• Validates migration path completeness

Novel Insights:

• 100% migration despite 67% documentation gaps (internal coordination worked)
• Three different deprecation strategies with no policy
• Schema deprecation field unused despite JSON Schema support
• stop-time error message is gold standard for API deprecations

---

References:

• compiler.go:594-596 (stop-time deprecation)
• safe_jobs.go:331-360 (safe-jobs backwards compat)
• frontmatter.go:681-693 (@import warning)

AI generated by Schema Consistency Checker

[github-actions[bot]]

This discussion was automatically closed because it was created by an agentic workflow more than 1 week ago.