Changelog profile parity - phase 1 & 2

[lcawl]

Summary

This pull request implements the first two phases of an effort to get the profile-based docs-builder changelog bundle and docs-builder changelog remove invocations to parity with the command-line-option method.

Design Principles

1. Mutually exclusive invocation: When using a profile (changelog bundle <profile> <arg> or changelog remove <profile> <arg>), any filter- or output-related command options must be rejected with an error. Profile config provides all such values.
2. Allow minimal CLI overrides: Only for remove: --dry-run and --force may be used with profiles. No other CLI options are allowed when using a profile.
3. Path derivation from config: When using a profile, paths are derived from the changelog configuration file (discovered by default, e.g. docs/changelog.yml):
   • Input directory (bundle.directory): The directory containing changelog YAML files for both bundle and remove.
   • Bundles directory (bundle.output_directory): For remove, the directory scanned for bundle dependencies. No --config or --directory override — profile invocations rely on the config file.
4. Core functionality parity: Both invocation styles must support the same core filtering and output behaviors; profiles achieve this via config fields.

---

Phase 1: Mutual Exclusivity and Bug Fix

1.1 Reject extra options when using profile mode

Files: ChangelogCommand.cs

For both Bundle and Remove:

• When isProfileMode is true, after validating profileArg is present, add a single check that rejects any of the following if specified:
  • Bundle: --all, --input-products, --output-products, --prs, --issues, --output, --repo, --owner, --resolve, --no-resolve, --hide-features, --config, --directory
  • Remove: --all, --products, --prs, --issues, --repo, --owner, --config, --directory, --bundles-dir
• Allow with profile: For remove only, --dry-run and --force. For bundle, no CLI options allowed.
• Emit a clear error: e.g. "When using a profile, do not specify --<option>. Paths and filters come from the changelog configuration. Allowed options with profiles (remove only): --dry-run, --force."
• Return exit code 1 and exit before invoking the service.

Outcome: This fixes the incidental bug (silent --output discard) and enforces mutual exclusivity.

1.2 Derive paths from config in profile mode

When using a profile, the changelog configuration file supplies all paths. Profile-based commands require the config file to exist; if it cannot be found, return an error.

Config discovery for profile mode:

• Try, in order: ./changelog.yml, then ./docs/changelog.yml (relative to current working directory).
• This ensures profile-based commands work when run from the folder containing the config, even if that folder does not follow the default convention (e.g. my-custom/path/changelog.yml — run from my-custom/path/ to find it).
• No --config override in profile mode.

If config not found: Return an error (do not fall back to defaults). Error message should advise:

• Create the configuration by running docs-builder changelog init, or
• Re-run the command from the folder where changelog.yml exists (e.g. if the config is in docs/, run from the project root; if the config is in my-folder/, run from my-folder/).

Path derivation from config:

• Input directory: Use bundle.directory from config. Ensure ChangelogBundlingService.ApplyConfigDefaults and ChangelogRemoveService.ApplyConfigDefaults use config when CLI did not supply --directory (which will always be the case in profile mode).
• Bundles directory (remove only): Use bundle.output_directory from config for the dependency check. Ensure ChangelogRemoveService.ResolveBundlesDirectory uses config when BundlesDir was not supplied (always in profile mode).

Implementation note: ChangelogConfigurationLoader.LoadChangelogConfiguration currently returns ChangelogConfiguration.Default with a warning when the file is missing. For profile mode, the caller (or loader when invoked with profile context) must treat a missing config as a hard error and emit the advice above.

1.3 Bundle-specific validation

• Move the profile-vs-options rejection so it runs before processedOutput is computed from --output, since we will now error on --output in profile mode.
• Ensure that when profile is used, the service receives Output = null so it uses the profile's output pattern (no need to merge CLI output anymore).

---

Phase 2: Profile Config Enhancements (Changelog Bundle)

2.1 Add output_products to profile config

Files:

• ChangelogConfigurationYaml.cs: Add OutputProducts (string?) to BundleProfileYaml.
• BundleConfiguration.cs: Add OutputProducts (string?) to BundleProfile.
• ChangelogConfigurationLoader.cs: Map OutputProducts from YAML to domain in ParseBundleConfiguration.
• ChangelogBundlingService.cs: In ProcessProfile, when a profile has output_products, parse it via ProfileFilterResolver.ParseProfileProducts (or reuse ProductInfoParser) and set OutputProducts on the returned input.

Config example:

profiles:
  kibana-release:
    products: "kibana {version}, security {version}, observability {version}"
    output_products: "kibana {version}"
    output: "kibana-{version}.yaml"

2.2 Add repo and owner to profile config

Files: Same YAML/domain/config-loader files as above.

• Add Repo (string?) and Owner (string?) to BundleProfileYaml and BundleProfile.
• In ProcessProfile, when the profile defines repo or owner, set them on the returned input.
• If neither is set in the profile, the bundle's product entries will have no repo field — the same state that already exists without --repo in option-based mode. The existing render-time fallback (product ID used as repo) applies, which may produce broken links when product ID ≠ GitHub repo name. Users who need correct links must set repo in the profile config.

No automatic derivation: Unlike option-based mode where --repo is explicit, profile mode has no --repo flag. The products.yml repository field is not a reliable source for automatic derivation, because its absence is ambiguous — some products genuinely share their name with their GitHub repo (e.g. elasticsearch), while others do not but have no repository field recorded (e.g. cloud-serverless, whose GitHub repo is cloud). Attempting to derive repo from product.Repository ?? productId would silently produce broken links for the latter case.

For option-based mode: No change. --repo and --owner are already explicit; existing behavior is unchanged.

Future improvement (out of scope): Populating missing repository fields in products.yml for products where product ID ≠ GitHub repo name (such as cloud-serverless → cloud) would improve render-time link resolution for both modes. This is a separate cleanup task.

2.2.1 Implementation changes

NOTE: This plan changed over the course of the PR, since I decided to add a "default" bundle.repo and bundle.owner that can be optionally overridden at the profile level. These values can then serve as the default for the --repo and --owner in the non-profile scenario too.

The change affected:

• ChangelogBundlingService.ApplyConfigDefaults — adds Repo = input.Repo ?? config.Bundle.Repo and Owner = input.Owner ?? config.Bundle.Owner
• ChangelogRemoveService.ApplyConfigDefaults — same

Precedence for both services and both modes:

explicit --repo / --owner CLI flag
  → bundle.repo / bundle.owner in changelog.yml
    → nothing (renderer falls back to product ID at render time)

So for a repo like cloud where cloud-serverless is the product ID, you can now set it once in changelog.yml:

bundle:
  repo: cloud
  owner: elastic

...and never need --repo cloud --owner elastic on the command line again, whether you're using option-based or profile-based commands.

---

Phase 5: Documentation and Examples

This pull request also includes the following pieces of phase 5:

Tests

(7 new tests across 2 files):

BundleChangelogsTests.cs:

• BundleChangelogs_WithProfile_OutputProducts_OverridesProductsArray — verifies that output_products in a profile replaces the products array in the bundle output (using wildcard lifecycle to match preview changelogs while advertising ga in the output)
• BundleChangelogs_WithProfile_RepoAndOwner_WritesValuesToProductEntries — verifies that repo from a profile is written to the bundle product entries (owner is for normalization only, not persisted in the bundle)
• BundleChangelogs_WithProfile_NoRepoOwner_PreservesExistingFallbackBehavior — verifies that a profile without repo/owner produces clean output with no repo: field
• BundleChangelogs_WithProfileMode_MissingConfig_ReturnsErrorWithAdvice — verifies error with advice when no changelog.yml is found
• BundleChangelogs_WithProfileMode_ConfigAtCurrentDir_LoadsSuccessfully — verifies auto-discovery of ./changelog.yml
• BundleChangelogs_WithProfileMode_ConfigAtDocsSubdir_LoadsSuccessfully — verifies auto-discovery of ./docs/changelog.yml

ChangelogRemoveTests.cs:

• Remove_WithProfileMode_MissingConfig_ReturnsErrorWithAdvice — verifies that the remove command also returns a clear error when no config is discoverable

Documentation

(docs/contribute/changelog.md):

• Restructured the "Create bundles" section to introduce the mutual exclusivity concept upfront, separating option-based and profile-based usage into their own subsections
• Added a full profile field reference table (products, output, output_products, repo, owner, hide_features) with example config
• Updated the "Removal with profiles" section to document mutual exclusivity, --dry-run/--force exceptions, config auto-discovery, and which profile fields are ignored during removal

Steps to test

1. Create a changelog configuration file and changelogs (e.g. use https://github.com/elastic/cloud/pull/150210)
2. Add the new changelog configuration options to see if you can generate the same bundles using only the profiles. For example, instead of a command like this:

   docs-builder changelog bundle \
   --input-products "cloud-hosted 2025-11-* *" \
   --config ./docs/changelog.yml \
   --directory ./docs/changelog \
   --output ./docs/releases/cloud-hosted/cloud-2025-11.yaml \
   --resolve --repo cloud \
   --output-products "cloud-hosted 2025-11" 

   Update the changelog configuration file to contain profiles like this:

   bundle:
     directory: docs/changelog
     resolve: true
     repo: cloud
     owner: elastic
     profiles:
       cloud-hosted-monthly:
         products: "cloud-hosted {version}-* *"
         output: "./docs/releases/cloud-hosted/cloud-{version}.yaml"
         output_products: "cloud-hosted {version}"

   Then run profile-based commands:

   docs-builder changelog bundle cloud-hosted-monthly 2025-11
   docs-builder changelog bundle cloud-hosted-monthly 2025-12
   docs-builder changelog bundle cloud-hosted-monthly 2026-01
   docs-builder changelog bundle cloud-hosted-monthly 2026-02

   When I performed this test, the bundles produced via both methods were identical.
3. Try adding extra command options to the profile-based command and confirm that it gets an error, for example:

   Error: When using a profile, the following options are not allowed: --output. All paths and filters are derived from the changelog configuration file.

   This error is returned for both the "bundle" and "remove" commands.
4. Try putting the changelog configuration file in a non-default location and confirm that it gets an error:

   Error: changelog.yml not found. Profile-based commands require a changelog configuration file.
   Either run 'docs-builder changelog init' to create one, or re-run this command from the folder where changelog.yml exists (e.g. the project root if the file is at docs/changelog.yml).

   Unless you run the command from the same directory as the configuration file, which works as long as you have appropriately relative paths in the bundle.directory and bundle.output_directory settings.
5. Verify that the "remove" command can still successfully find and delete changelog files. For example, this works:

   docs-builder changelog remove cloud-hosted-monthly 2026-02

Reviewer notes

I identified that this new output_products option doesn't currently work with the promotion report option. The AI analysis indicated that's better to address in phase 3, which already planned to make changes to the promotion report functionality (so that it worked as a command option too).

Generative AI disclosure

1. Did you use a generative AI (GenAI) tool to assist in creating this contribution?

• Yes
• No

3. If you answered "Yes" to the previous question, please specify the tool(s) and model(s) used (e.g., Google Gemini, OpenAI ChatGPT-4, etc.).

Tool(s) and model(s) used: composer-1.5, claude-4.6-sonnet-medium

[github-actions]

🔍 Preview links for changed docs

• docs/cli/release/changelog-bundle.md
• docs/cli/release/changelog-remove.md
• docs/contribute/changelog.md