[DOCS] Add changelog.yml config file

docs/changelog.yml

@@ -0,0 +1,316 @@
+# 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: pr
+
+# Products configuration (optional)
+# If not specified, all products from products.yml are allowed (including those
+# that have 'public-reference' disabled).
+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: true
+
+# Available lifecycle values (strongly typed: preview, beta, ga)
+# Accepts string or list: "preview, beta, ga" or a YAML list
+lifecycles:
+  - preview
+  - beta
+  - ga
+  - experimental
+
+# 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"
+    docs: ">docs"
+    enhancement: ">enhancement"
+    feature: ">feature"
+    regression: "regression"
+    # Empty block: no labels (YAML null)
+    deprecation: 
+    known-issue:
+    other:
+    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
+    Machine Learning: ":ml"
+    # 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"
+
+  # Feature ID definitions with labels (optional).
+  # Keys are feature-id values written to the changelog; values are label strings or lists.
+  # When a PR has a matching label and --feature-id is not set, that feature-id is applied.
+  # If multiple labels map to distinct feature-ids, a warning is emitted and the first match is used.
+  # Precedence: --feature-id CLI option > pivot.features label mapping.
+  # Unreleased feature IDs should also be listed under bundle.profiles.<name>.hide_features.
+  #
+  # features:
+  #   'feature:new-search-api':
+  #     - "feature-flag:new-search-api"
+  #     - ":Feature/NewSearchApi"
+
+# 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/configure-changelogs-ref.md#rules).
+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 https://github.com/elastic/docs-builder/blob/main/docs/contribute/configure-changelogs-ref.md#rules-bundle 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
+  # Optional: default description text for bundles. Supports {version}, {lifecycle}, {owner}, and {repo} placeholders.
+  # Use YAML literal block scalar (|) for multiline descriptions.
+  # description: |
+  #   This release includes new features and bug fixes.
+  #   
+  #   For more information, see the [release notes](https://www.elastic.co/docs/release-notes/product#product-{version}).
+  owner: elastic
+  repo: ml-cpp
+  link_allow_repos:
+    - elastic/ml-cpp
+    - elastic/elasticsearch
+    - elastic/kibana
+    - elastic/roadmap
+  # 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.
+  # There is no implicit allow: you must list every repo whose links should appear, including your
+  # own (bundle.repo as owner/repo). When omitted entirely, no link filtering is applied.
+  # Run `changelog init` in a GitHub clone to pre-fill owner, repo, and link_allow_repos, or set
+  # bundle.owner, bundle.repo, and link_allow_repos manually. Example — allow only this repo:
+  # link_allow_repos:
+  #   - elastic/kibana
+  # To allow cross-repo links, add more owner/repo entries (for example elastic/elasticsearch).
+  # 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
+  # Optional: branch whose CDN changelog pool (changelog/{org}/{repo}/{branch}/...) is sourced from when
+  # bundling entries from the CDN. Defaults to "main" when unset. Can be overridden per profile.
+  # branch: main
+  # Optional: control auto-population of release-date for all profiles by default.
+  # When true (default), auto-populate release dates. Profiles can override this setting.
+  release_dates: true
+
+  # 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_products', 'repo', 'owner', and 'hide_features' fields are
+  # bundle-specific and are ignored for removal.
+  # Bundle file names are derived by convention as '{repo}-{product}-{version}.yaml' from the
+  # authoring repo and the profile's primary output product; setting an explicit 'output'
+  # pattern is an error. If no repo can be resolved, the name falls back to '{product}-{version}.yaml'.
+  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}"
+    #   # The bundle's products metadata; also determines the conventional output
+    #   # file name ({repo}-{product}-{version}.yaml from the authoring repo and the first product).
+    #   output_products: "elasticsearch {version}"
+    #   # Optional: profile-specific description (overrides bundle.description)
+    #   # description: |
+    #   #   Elasticsearch {version} includes:
+    #   #   - Performance improvements
+    #   #   - Bug fixes and stability enhancements
+    #   #   
+    #   #   Download the release binaries: https://github.com/{owner}/{repo}/releases/tag/v{version}
+    #   # Optional: control auto-population of release-date for this profile.
+    #   # When true (default), auto-populate release dates. When false, equivalent to --no-release-date.
+    #   # release_dates: true
+    # 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_products: "elasticsearch {version} {lifecycle}"
+
+    # Example: Serverless release profile (filter by promotion report, PR, or issue list)
+    # serverless-release:
+    #   output_products: "cloud-serverless {version}"           # omit lifecycle
+    #   # output_products: "cloud-serverless {version} {lifecycle}"  # derive (ga for ISO dates)
+    #   # output_products: "cloud-serverless {version} preview"      # hardcode for exceptional releases
+    #   # Optional: replace bundle.output_directory for this profile (same as --output as a directory).
+    #   # The conventional {repo}-{product}-{version}.yaml name is written in this folder.
+    #   # output_directory: docs/releases/cloud-serverless
+    #   # Optional: GitHub repository for link and file name generation (overrides bundle.repo if set)
+    #     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}"