[DOCS] Split changelog how-to into subpages

Author: lcawl

config/changelog.example.yml

@@ -150,7 +150,7 @@ pivot:
 #   - 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).
+# For details and examples, refer to the [rules documentation](https://github.com/elastic/docs-builder/blob/main/docs/contribute/configure-changelogs.md#rules).
 rules:
   # match: any
 
@@ -169,7 +169,7 @@ rules:
   #       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.
+  # See https://github.com/elastic/docs-builder/blob/main/docs/contribute/configure-changelogs.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):
@@ -213,7 +213,7 @@ bundle:
   # Whether to resolve (copy contents) by default
   resolve: true
   # Optional: default description text for bundles. Supports {version}, {lifecycle}, {owner}, and {repo} placeholders.
-  # Use YAML literal block scalar (|) for multiline descriptions. See docs/contribute/changelog.md for examples.
+  # Use YAML literal block scalar (|) for multiline descriptions.
   # description: |
   #   This release includes new features and bug fixes.
   #   

docs/_docset.yml

@@ -69,6 +69,11 @@ toc:
       - file: add-repo.md
       - file: release-new-version.md
       - file: changelog.md
+        children:
+          - file: configure-changelogs.md
+          - file: create-changelogs.md
+          - file: bundle-changelogs.md
+          - file: publish-changelogs.md
       - hidden: locally.md
       - hidden: on-the-web.md
   - folder: building-blocks

docs/cli/changelog/add.md

@@ -1,7 +1,7 @@
 # changelog add
 
 Create a changelog file that describes a single item in the release documentation.
-For details and examples, go to [](/contribute/changelog.md).
+For details and examples, go to [](/contribute/create-changelogs.md).
 
 ## Usage
 
@@ -169,3 +169,19 @@ When you run the `changelog add` command without the `--products` option, it res
 5. **Error** — if none of the above resolves to at least one product, an error is raised.
 
 Product-specific `rules.create` rules are evaluated *after* products are resolved from labels, so label-derived products correctly participate in per-product create rule checks.
+
+## Configuration checks
+
+By default, the command checks the following path for a configuration file: `docs/changelog.yml`.
+You can specify a different path with the `--config` command option.
+
+If a configuration file exists, the command validates its values before generating changelog files:
+
+- If the configuration file contains `lifecycles`, `products`, `subtype`, or `type` values that don't match the values in `ChangelogEntryType.cs`, `ChangelogEntrySubtype.cs`, or `Lifecycle.cs`, validation fails.
+- If the configuration file contains `areas` values and they don't match what you specify in the `--areas` command option, validation fails.
+- If the configuration file contains `lifecycles` or `products` values that are a subset of the available values and you try to create a changelog with values outside that subset, validation fails.
+
+In each of these cases where validation fails, a changelog file is not created.
+
+If the configuration file contains `rules.create` definitions and a PR or issue has a blocking label, that PR is skipped and no changelog file is created for it.
+For more information, refer to [Rules for creation and publishing](/contribute/configure-changelogs.md#rules).

docs/cli/changelog/bundle-amend.md

@@ -4,7 +4,7 @@ Amend a bundle with additional changelog entries.
 Amend bundles follow a specific naming convention: `{parent-bundle-name}.amend-{N}.yaml` where `{N}` is a sequence number.
 
 To create a bundle, use [](/cli/changelog/bundle.md).
-For details and examples, go to [](/contribute/changelog.md).
+For details and examples, go to [](/contribute/bundle-changelogs.md).
 
 ## Usage
 

docs/cli/changelog/bundle.md

@@ -93,7 +93,7 @@ You must choose one method for determining what's in the bundle (`--all`, `--inp
 
 `--input-products <List<ProductInfo>?>`
 :   Filter by products in the format "product target lifecycle, ...".
-:   For more information about the valid product and lifecycle values, go to [Product format](/contribute/changelog.md#product-format).
+:   For more information about the valid product and lifecycle values, go to [Product format](/contribute/create-changelogs.md#product-format).
 :   When specified, all three parts (product, target, lifecycle) are required but can be wildcards (`*`). Multiple comma-separated values are combined with OR: a changelog is included if it matches any of the specified product/target/lifecycle combinations. For example:
 
 - `"cloud-serverless 2025-12-02 ga, cloud-serverless 2025-12-06 beta"` — include changelogs for either cloud-serverless 2025-12-02 ga or cloud-serverless 2025-12-06 beta
@@ -103,7 +103,7 @@ You must choose one method for determining what's in the bundle (`--all`, `--inp
 - `"* * *"` - match all changelogs (equivalent to `--all`)
 
 :::{note}
-The `--input-products` option determines which changelog files are gathered for consideration. **`rules.bundle` is not disabled** when you use `--input-products` — global `include_products` / `exclude_products`, type/area rules, and (when configured) per-product rules still run **after** matching, unless your configuration is in [no-filtering mode](/contribute/changelog.md#bundle-rule-modes). The only “mutually exclusive” pairing on this command is **profile-based** bundling versus **option-based** flags (see [Usage](#usage)), not `--input-products` versus `rules.bundle`.
+The `--input-products` option determines which changelog files are gathered for consideration. **`rules.bundle` is not disabled** when you use `--input-products` — global `include_products` / `exclude_products`, type/area rules, and (when configured) per-product rules still run **after** matching, unless your configuration is in [no-filtering mode](/contribute/configure-changelogs.md#bundle-rule-modes). The only “mutually exclusive” pairing on this command is **profile-based** bundling versus **option-based** flags (see [Usage](#usage)), not `--input-products` versus `rules.bundle`.
 :::
 
 `--issues <string[]?>`
@@ -122,7 +122,7 @@ The `--input-products` option determines which changelog files are gathered for
 `--output-products <List<ProductInfo>?>`
 :   Optional: Explicitly set the products array in the output file in format "product target lifecycle, ...".
 :   This value replaces information that would otherwise be derived from changelogs.
-:   When `rules.bundle.products` per-product overrides are configured, `--output-products` also supplies the product IDs used to choose the **rule context product** (first alphabetically) for Mode 3. To use a different product's rules, run a separate bundle with only that product in `--output-products`. For details, refer to [Single-product rule resolution algorithm](/contribute/changelog.md#changelog-bundle-rule-resolution).
+:   When `rules.bundle.products` per-product overrides are configured, `--output-products` also supplies the product IDs used to choose the **rule context product** (first alphabetically) for Mode 3. To use a different product's rules, run a separate bundle with only that product in `--output-products`. For details, refer to [Product-specific bundle rules](/contribute/configure-changelogs.md#rules-bundle-products).
 
 `--owner <string?>`
 :   Optional: The GitHub repository owner, required when pull requests or issues are specified as numbers.
@@ -243,7 +243,7 @@ This may result in broken links if the product ID doesn't match the GitHub repos
 
 The `rules.bundle` section in the changelog configuration file lets you filter entries during bundling. It applies to both `changelog bundle` and `changelog gh-release`, after entries are matched by the primary filter (`--prs`, `--issues`, `--all`, **`--input-products`**, and so on) and before the bundle is written.
 
-Which `rules.bundle` fields take effect depends on the [bundle rule modes](/contribute/changelog.md#bundle-rule-modes) (no filtering, global rules against each changelog’s content, or per-product rule context). Input stage (gathering entries) and bundle filtering stage (filtering for output) are conceptually separate.
+Which `rules.bundle` fields take effect depends on the [bundle rule modes](/contribute/configure-changelogs.md#bundle-rule-modes) (no filtering, global rules against each changelog’s content, or per-product rule context). Input stage (gathering entries) and bundle filtering stage (filtering for output) are conceptually separate.
 
 The following fields are supported:
 
@@ -272,7 +272,7 @@ The following fields are supported:
 :   Match mode for the area filter (`any`, `all`, or `conjunction`). Inherits from `rules.match` when not specified.
 
 `products`
-:   Per-product filter overrides for **all filter types** (product, type, area). Keys are product IDs (or comma-separated lists). When this map is **non-empty**, the bundler uses **per-product rule context** mode: global `rules.bundle` product/type/area fields are **not** used for filtering (repeat constraints under each product key if you still need them). For details, refer to [Bundle rule modes](/contribute/changelog.md#bundle-rule-modes) and [Single-product rule resolution (Mode 3 only)](/contribute/changelog.md#changelog-bundle-rule-resolution).
+:   Per-product filter overrides for **all filter types** (product, type, area). Keys are product IDs (or comma-separated lists). When this map is **non-empty**, the bundler uses **per-product rule context** mode: global `rules.bundle` product/type/area fields are **not** used for filtering (repeat constraints under each product key if you still need them). For details, refer to [Bundle rule modes](/contribute/configure-changelogs.md#bundle-rule-modes) and [Product-specific bundle rules](/contribute/configure-changelogs.md#rules-bundle-products).
 
 ```yaml
 rules:
@@ -448,7 +448,7 @@ If your configuration file defines a standard profile (that is to say, not a Git
 | `9.2.0-alpha.1` | `preview` |
 | `9.2.0-preview.1` | `preview` |
 
-For more information about acceptable product and lifecycle values, go to [Product format](/contribute/changelog.md#product-format).
+For more information about acceptable product and lifecycle values, go to [Product format](/contribute/create-changelogs.md#product-format).
 
 You can invoke those profiles with commands like this:
 

docs/cli/changelog/gh-release.md

@@ -58,9 +58,9 @@ The product, target version, and lifecycle are inferred automatically from the r
 ## Configuration
 
 The `rules.bundle` section of your `changelog.yml` applies to bundles created by this command (after changelog files are gathered from the release).
-Which fields take effect depends on [bundle rule modes](/contribute/changelog.md#bundle-rule-modes).
+Which fields take effect depends on [bundle rule modes](/contribute/configure-changelogs.md#bundle-rule-modes).
 For details, refer to [Rules for filtered bundles](/cli/changelog/bundle.md#changelog-bundle-rules).
-If you use per-product rule overrides, refer to [Single-product rule resolution (Mode 3 only)](/contribute/changelog.md#changelog-bundle-rule-resolution).
+If you use per-product rule overrides, refer to [Product-specific bundle rules](/contribute/configure-changelogs.md#rules-bundle-products).
 
 ## Examples
 

docs/cli/changelog/remove.md

@@ -11,7 +11,7 @@ These modes are mutually exclusive. You can't combine a profile argument with th
 
 Before deleting anything, the command checks whether any of the matching files are referenced by unresolved bundles, to prevent silently breaking the `{changelog}` directive.
 
-For more context, go to [](/contribute/changelog.md#changelog-remove).
+For more context, go to [](/contribute/bundle-changelogs.md#changelog-remove).
 
 ## Usage
 

docs/cli/changelog/render.md

@@ -3,7 +3,7 @@
 Generate markdown or asciidoc files from changelog bundle files.
 
 To create the bundle files, use [](/cli/changelog/bundle.md).
-For details and examples, go to [](/contribute/changelog.md).
+For details and examples, go to [](/contribute/publish-changelogs.md).
 
 ## Usage
 
@@ -60,7 +60,7 @@ The `render` command automatically discovers and merges `.amend-*.yaml` files wi
 :   Defaults to the version in the first bundle.
 :   If the string contains spaces, they are replaced with dashes when used in directory names and anchors.
 
-The `changelog render` command does **not** use `rules.publish` for filtering. Filtering must be done at bundle time using `rules.bundle`. For more information, refer to [](/contribute/changelog.md). For how the directive differs, see the [{changelog} directive syntax reference](/syntax/changelog.md).
+The `changelog render` command does **not** use `rules.publish` for filtering. Filtering must be done at bundle time using `rules.bundle`. For more information, refer to [](/contribute/publish-changelogs.md). For how the directive differs, see the [{changelog} directive syntax reference](/syntax/changelog.md).
 
 ## Output formats