# VibeCollab Changelog Schema v1
# Defines structure for docs/changelog.yaml
#
# Design goals:
#   - Structured version releases with categorized entries
#   - Support "Unreleased" section for in-progress work
#   - Entries are descriptive strings (for AI understanding + Markdown rendering)
#   - Forward-compatible via version field

changelog:
  type: object
  required: [kind, version, releases]
  properties:
    kind:
      type: string
      const: "changelog"
      description: Fixed type identifier

    version:
      type: string
      default: "1"
      description: Schema version for migration compatibility

    unreleased:
      $ref: "#/release"
      description: In-progress changes not yet tagged as a release

    releases:
      type: array
      description: Released versions, newest first
      items:
        $ref: "#/release"

    planned:
      type: array
      description: Planned future releases (preview / roadmap summary)
      items:
        type: object
        required: [target_version]
        properties:
          target_version:
            type: string
            description: Target version (e.g. "v0.12.0")
          summary:
            type: string
            description: Brief summary of planned changes

    decisions:
      type: array
      description: Decision references relevant to changelog scope
      items:
        type: string
        description: Decision ID (e.g. "DECISION-019")

# ============================================
# Release Entry
# ============================================
release:
  type: object
  required: [release_version]
  properties:
    release_version:
      type: string
      description: Version tag (e.g. "v0.10.14") or "unreleased"

    date:
      type: string
      format: date
      description: Release date (YYYY-MM-DD)

    title:
      type: string
      description: Optional release title / codename

    added:
      type: array
      items:
        $ref: "#/changelog_entry"
      description: New features / additions

    changed:
      type: array
      items:
        $ref: "#/changelog_entry"
      description: Changes to existing functionality

    fixed:
      type: array
      items:
        $ref: "#/changelog_entry"
      description: Bug fixes

    removed:
      type: array
      items:
        $ref: "#/changelog_entry"
      description: Removed features

    deprecated:
      type: array
      items:
        $ref: "#/changelog_entry"
      description: Deprecated features

    security:
      type: array
      items:
        $ref: "#/changelog_entry"
      description: Security-related changes

    notes:
      type: string
      description: Additional release notes (free-form)

# ============================================
# Changelog Entry
# ============================================
changelog_entry:
  type: object
  required: [description]
  properties:
    description:
      type: string
      description: Entry description (rich text, supports inline references)

    task_ids:
      type: array
      items:
        type: string
      description: Associated task IDs (e.g. ["TASK-DEV-026"])

    insight_ids:
      type: array
      items:
        type: string
      description: Associated insight IDs (e.g. ["INS-039"])

    decision_ids:
      type: array
      items:
        type: string
      description: Associated decision IDs

    details:
      type: array
      items:
        type: string
      description: Sub-items / bullet points for this entry
