changelog.example.yml

# Changelog Configuration
# This file configures the valid values for changelog fields using the pivot structure.
# Place this file as `changelog.yml` in the `docs/` directory
#
# NOTE: All list-like fields accept BOTH forms:
#   - Comma-separated string: "value1, value2, value3"
#   - YAML list:
#     - value1
#     - value2
#     - value3
# Both forms produce the same result. Choose whichever is more readable for your use case.

# Filename strategy for generated changelog files.
# Controls how files created by 'changelog add' are named.
#   pr        — use the PR number (e.g., 12345.yaml).
#   issue     — use the issue number (e.g., 67890.yaml).
#   timestamp — use a Unix timestamp with a title slug (e.g., 1735689600-fix-search.yaml). Default.
# Can be overridden per invocation with --use-pr-number or --use-issue-number CLI flags.
filename: timestamp

# Products configuration (optional)
# If not specified, all products from products.yml are allowed (including those
# that only have the 'release-notes' feature enabled).
products:
  # List of available product IDs (empty = all from products.yml)
  # Accepts string or list: "elasticsearch, kibana" or [elasticsearch, kibana]
  available: []
  # Default products when --products not specified
  # default:
  #   - product: elasticsearch
  #     lifecycle: ga

# Extraction configuration
# Controls automatic extraction of information from PR descriptions
extract:
  # Auto-extract release notes from PR descriptions (default: true)
  # Can be overridden by CLI --no-extract-release-notes
  release_notes: true
  # Auto-extract linked references (default: true)
  # When using --prs: looks for patterns like "Fixes #123", "Closes #456" in PR body to derive issues.
  # When using --issues: looks for patterns like "Fixed by #123" in issue body to derive PRs.
  # Can be overridden by CLI --no-extract-issues
  issues: true
  # Remove square-bracket prefixes from PR titles (default: false)
  # When enabled (true or via --strip-title-prefix), titles like "[ES|QL] Fix bug" become "Fix bug".
  # Can be overridden by CLI --strip-title-prefix
  strip_title_prefix: false

# Available lifecycle values (strongly typed: preview, beta, ga)
# Accepts string or list: "preview, beta, ga" or a YAML list
lifecycles:
  - preview
  - beta
  - ga

# Pivot configuration for types, subtypes, and areas with label mappings.
# By default we render changelogs grouped by type > subtype > area.
# NOTE: subtype and area are optional and either may be omitted.
# Labels are specified in a "label -> value" format
pivot:
  # Type definitions with optional labels
  # At a minimum, feature, bug-fix, and breaking-change must be configured.
  # Keys are type names, values can be:
  #   - simple string: comma-separated label list (e.g., ">bug, >fix")
  #   - YAML list: [">bug", ">fix"]
  #   - empty/null: no labels for this type
  #   - object: { labels: "...", subtypes: {...} } for breaking-change type only
  #     (labels and subtype values also accept string or list)
  types:
    # Complex object form with subtypes (ONLY allowed for breaking-change)
    # Subtypes help categorize breaking changes by their nature
    # Both labels and subtype values accept string or list form
    breaking-change:
      labels: ">breaking, >bc"
      # Equivalent list form:
      # labels:
      #   - ">breaking"
      #   - ">bc"
      subtypes:
        api: ">api-breaking"
        behavioral: ">behavioral-breaking"
        configuration: ">config-breaking"
        dependency: ">dependency-breaking"
        subscription: ">subscription-breaking"
        plugin: ">plugin-breaking"
        security: ">security-breaking"
        other:
    # Simple string form: labels as comma-separated string
    bug-fix: ">bug"
    deprecation: ">deprecation"
    # Empty block: no labels (YAML null)
    feature:
    enhancement:
    docs:
    known-issue:
    other:
    regression:
    security:

  # Labels that trigger the highlight flag (accepts string or list)
  # String form: highlight: ">highlight, >release-highlight"
  # List form:
  # highlight:
  #   - ">highlight"
  #   - ">release-highlight"

  # Area definitions with labels
  # Keys are area display names (can contain commas), values are label strings or lists
  # Each label maps to exactly one area.
  # String form: "label1, label2" | List form: [label1, label2]
  # To map one label to multiple areas, repeat the label under each area name.
  areas:
    # Example mappings - customize based on your label naming conventions
    # Autoscaling: ":Distributed Coordination/Autoscaling"
    # Search: ":Search/Search"
    # Security: ":Security/Security"
    # Watcher: ":Data Management/Watcher"
    # To map a label to multiple areas (e.g., "Team:Search" to both "Search" and "Observability"):
    # Search:
    #   - ":Search/Search"
    #   - "Team:Search"
    # Observability:
    #   - "Team:Search"
    # List form example:
    # Search:
    #   - ":Search/Search"
    #   - ":Search/Ranking"

  # Product definitions with labels (optional).
  # Keys are product spec strings; values are label strings or lists that trigger that product.
  # A product spec string is: "<product-id> [<target-version>] [<lifecycle>]"
  #   - Product ID only:           "elasticsearch"
  #   - Product + target:          "kibana 9.2.0"
  #   - Full spec:                 "cloud-serverless 2025-06 ga"
  # When a PR has labels matching any product entry, all matching products are added.
  # Precedence: --products CLI option > pivot.products label mapping > products.default > repo inference.
  #
  # products:
  #   'elasticsearch':
  #     - ":stack/elasticsearch"
  #   'kibana':
  #     - ":stack/kibana"
  #   'cloud-serverless':
  #     - ":cloud/serverless"
  #   # Specify a target version if known:
  #   # 'elasticsearch 9.2.0':
  #   #   - ":feature/new-in-9.2"

# Rules configuration — controls which PRs create changelogs and which changelogs are published.
# All list-like fields (exclude, include, exclude_types) accept BOTH forms:
#   - Comma-separated string: "value1, value2, value3"
#   - YAML list: [value1, value2, value3]
#
# For details and examples, refer to the [rules documentation](https://github.com/elastic/docs-builder/blob/main/docs/contribute/changelog.md#rules-for-creation-and-bundling).
rules:
  # match: any

  # Create — controls which PRs generate changelogs.
  # create:
  #   exclude: ">non-issue, >test"
  #   # Or equivalently:
  #   # exclude:
  #   #   - ">non-issue"
  #   #   - ">test"
  #   # match: any
  #   products:
  #     'elasticsearch, kibana':
  #       exclude: ">test"
  #     'cloud-serverless':
  #       exclude: "ILM"

  # Bundle — filtering applied during 'changelog bundle' and 'changelog gh-release'.
  # See docs/contribute/changelog.md → "Bundle rule modes" for Mode 1 / 2 / 3 behavior.
  #
  # Mode 2 (global content): use global lists only — no `products` key, or `products: {}`.
  # Example — include changelogs that list elasticsearch OR kibana (evaluated per changelog):
  # bundle:
  #   match_products: any
  #   include_products:
  #     - elasticsearch
  #     - kibana
  #   exclude_types: "deprecation, known-issue"
  #
  # Example — exclude only when the changelog lists BOTH products (conjunction); extras allowed:
  # bundle:
  #   match_products: conjunction
  #   exclude_products:
  #     - kibana
  #     - observability
  #
  # Mode 3 (per-product context): non-empty `rules.bundle.products` — global include/exclude/type/area
  # under `bundle:` are NOT applied for filtering; configure filters under each product key.
  # Example:
  # bundle:
  #   exclude_types: [docs]   # ignored for filtering in Mode 3 — duplicate under each product if needed
  #   products:
  #     observability:
  #       exclude_products: ["cloud-enterprise"]
  #       exclude_types: ["docs"]
  #       include_areas:
  #         - "APM"
  #         - "Infrastructure monitoring"
  #     kibana:
  #       match_products: all
  #       include_products: ["kibana", "security"]
  #       exclude_types: ["docs"]

# Bundle configuration (profiles and defaults)
bundle:
  # Input directory containing changelog YAML files
  directory: docs/changelog
  # Output directory for bundled changelog files
  output_directory: docs/releases
  # Whether to resolve (copy contents) by default
  resolve: true
  # PR/issue link allowlist: when set (including []), only links to these owner/repo pairs are kept
  # in bundle output; others are rewritten to '# PRIVATE:' sentinels (requires resolve: true).
  # When omitted, no link filtering is applied.
  # Add your repository and any others whose PR/issue links should appear in published docs.
  # link_allow_repos:
    # - elastic/elasticsearch
    # - elastic/kibana
  # Optional: default GitHub repo name applied to all profiles that do not specify their own.
  # Used by the {changelog} directive to generate correct PR/issue links when the product ID
  # differs from the GitHub repository name. Can be overridden per profile.
  # repo: elasticsearch
  # Optional: default GitHub owner applied to all profiles that do not specify their own.
  # owner: elastic

  # Named bundle profiles for different release scenarios.
  # Profiles can be used with both 'changelog bundle' and 'changelog remove':
  #   docs-builder changelog bundle elasticsearch-release 9.2.0
  #   docs-builder changelog remove elasticsearch-release 9.2.0
  # When used with 'changelog remove', only the 'products' field is applied.
  # The 'output', 'output_products', 'repo', 'owner', and 'hide_features' fields are
  # bundle-specific and are ignored for removal.
  profiles:
    # Example: Elasticsearch release profile (filter by changelog fields)
    # elasticsearch-release:
    #   # Filter: which input changelogs to include ({version} and {lifecycle} are substituted at runtime)
    #   products: "elasticsearch {version} {lifecycle}"
    #   # Output filename ({version} is substituted at runtime)
    #   output: "elasticsearch-{version}.yaml"
    #   # Optional: override the products array written to the bundle output.
    #   # output_products: "elasticsearch {version}"
    # Example: GitHub release profile (fetches PR list directly from a GitHub release)
    # Use when you want to bundle or remove changelogs based on a published GitHub release.
    # elasticsearch-gh-release:
    #   source: github_release       # Fetch PR list from GitHub release instead of filtering input changelogs
    #   repo: elasticsearch          # GitHub repository (required if bundle.repo is not set)
    #   owner: elastic               # GitHub owner (optional; defaults to bundle.owner or "elastic")
    #   output: "elasticsearch-{version}.yaml"
    #   output_products: "elasticsearch {version} {lifecycle}"

    # Example: Serverless release profile (filter by promotion report, PR, or issue list)
    # serverless-release:
    #   output: "serverless-{version}.yaml"
    #   output_products: "cloud-serverless {version}"
    #   # Optional: profile-specific GitHub repo name (overrides bundle.repo if set).
    #   # Only needed when this profile's product ID differs from the repository name.
    #     repo: elasticsearch
    #     owner: elastic
    #   # Feature IDs to hide when bundling with this profile (accepts string or list)
    #   hide_features:
    #     - feature-flag-1
    #     - feature-flag-2

    # Example: Multi-product profile (Mode 3 rule context = first product alphabetically, e.g. kibana).
    # For security-only rules, add a separate profile with output_products listing only security.
    # kibana-security-release:
    #   output: "kibana-security-{version}.yaml"
    #   output_products: "kibana {version}, security {version}"