Release Notes Feature Improvements

[cotti]

This PR implements several improvements to the changelog bundling, rendering, and directive functionality based on https://github.com/elastic/docs-eng-team/issues/374.

Summary

Change	Description
Hide features in bundles	--hide-features can now be specified when bundling, persisting hidden feature IDs in the bundle
Repository field for products	Bundles now store the actual GitHub repo name to generate correct PR/issue links
Amend bundle merging	Amend bundles (*.amend-N.yaml) are automatically merged with their parent bundles
Type-specific empty messages	The {changelog} directive shows appropriate empty messages based on the :type: filter
Automatic product blocker resolution	The {changelog} directive now auto-detects the product from single-product docsets for publish blockers

Changes

1. Move --hide-features to Bundle Command

Problem: Previously, --hide-features was only available on the render command, meaning the directive couldn't access this information and each rendering context needed to know which features to hide.

Solution:

• Added hide-features field to the bundle schema (BundleDto, Bundle, LoadedBundle)
• Added --hide-features option to changelog bundle command (supports comma-separated IDs and file paths)
• The {changelog} directive now aggregates hide-features from all loaded bundles
• The render command merges CLI --hide-features with bundle-sourced features

# Example bundle with hide-features
products:
  - product: elasticsearch
    target: 9.3.0
hide-features:
  - feature:hidden-api
  - feature:experimental
entries:
  - file:
      name: new-feature.yaml
      checksum: abc123

2. Fix Incorrect Repository URLs in Links

Problem: PR/issue links used the product ID (e.g., cloud-serverless) instead of the actual GitHub repository name (e.g., cloud), resulting in broken links.

Solution:

• Added repo field to BundledProductDto and BundledProduct
• When bundling with --repo, the repository name is stored in the bundle's product metadata
• BundleLoader uses the repo field for link generation, falling back to ProductId for backward compatibility

products:
  - product: cloud-serverless
    target: 2025-12-02
    repo: cloud  # Actual GitHub repo name

3. Fix Amend Bundles Appearing Separately

Problem: Bundles created with changelog bundle-amend appeared as separate releases instead of merging with their parent bundle.

Solution:

• Added MergeAmendFiles method to BundleLoader that automatically discovers and merges amend files
• Amend files follow the pattern {parent-bundle}.amend-{N}.yaml
• Parent bundle's metadata (products, hide-features, repo) is preserved
• Works with both .yaml and .yml extensions

bundles/
├── 9.3.0.yaml           # Parent bundle
├── 9.3.0.amend-1.yaml   # Auto-merged with parent
└── 9.3.0.amend-2.yaml   # Auto-merged with parent

4. Type-Specific Empty Section Text

Problem: When using :type: breaking-change filter with no entries, the message was generic ("No new features, enhancements, or fixes") instead of type-appropriate.

Solution:

• Added GetEmptyMessage(ChangelogTypeFilter) method to ChangelogInlineRenderer
• Empty sections now show contextually appropriate messages:
  • :type: breaking-change → "There are no breaking changes associated with this release."
  • :type: deprecation → "There are no deprecations associated with this release."
  • :type: known-issue → "There are no known issues associated with this release."

5. Automatic Product Blocker Resolution for Directives

Problem: The {changelog} directive wasn't respecting product-specific publish blockers (block.product.{productId}.publish) defined in changelog.yml. Users had to explicitly specify :product: kibana even when the docset only had one product configured.

Solution:

• Added ResolveProductId() method to ChangelogBlock that resolves the product ID in priority order:
  1. Explicit :product: option if specified
  2. Docset's single product ID (when exactly one product is configured in docset.yml)
  3. Falls back to global block.publish if no product can be determined
• Extended ReleaseNotesSerialization.LoadPublishBlocker to support product-specific blocker lookup
• Added minimal DTOs for deserializing block.product configuration

docset.yml - single product docset

products:
  - id: kibana

changelog.yml - product-specific blockers

block:
  product:
    kibana:
      publish:
        types:
          - docs
        areas:
          - "Elastic Observability solution"
          - "Elastic Security solution"

[github-actions]

🔍 Preview links for changed docs

• docs/cli/release/changelog-bundle.md
• docs/cli/release/changelog-render.md
• docs/contribute/changelog.md
• docs/syntax/changelog.md

[lcawl]

Move --hide-features to bundle command

I tested with the files from elastic/kibana#250840 and confirmed that the render command continues to successfully hide features. For example, it generated the following messages:

The following errors and warnings were found in the documentation

Warning: Changelog entry 'Feature branch ' with feature-id 'test_feature1' will be commented out in markdown output
 
Warning: Changelog entry 'Adds a functionality for removing root privilege from Fleet managed agents if applicable.' with feature-id 'test_feature3' will be commented out in markdown output

Likewise the changelog directive also successfully hides the "hidden" features.

Fix incorrect repository URLs in links

I tested and this works in elastic/kibana#250840
For example:

docs-builder changelog bundle \
--config./docs/changelog.yml \
--input-products "kibana 9.3.0 *" \
--directory ./docs/changelog \
--output ./docs/releases/kibana/9.3.0.yaml \
--repo kibana --owner elastic \
--output-products "kibana 9.3.0 *" \
--hide-features test_feature1

Created output that contains the repo clause:

products:
- product: kibana
  target: 9.3.0
  repo: kibana
hide-features:
- test_feature1
...

Ditto in lcawl/kibana#11 where

./docs-builder changelog bundle \
--directory ./docs/changelog/2025-01-13 \
--output ./docs/changelog/bundles/1.yaml \
--all \
--output-products "cloud-serverless 2025-01-13" \
--repo kibana --owner elastic

yields:

products:
- product: cloud-serverless
  target: 2025-01-13
  repo: kibana
entries:
- file: ...

However, the links are still behaving oddly when they're rendered in a situation where multiple bundles are merged.
For example, test with elastic/docs-content#4843 where I've refreshed the bundles to contain the repo clauses, but it's generating URLs like this:

[Traces][Discover] Fix double scroll in fullscreen flyouts. [#247744](https://github.com/elastic/elasticsearch+elasticsearch-serverless+kibana/pull/247744)

i.e. it's using all three repo values rather than the bundle-specific appropriate values (in this case, kibana).
You can see the right type of URLs generated from the render command with the same input files in elastic/docs-content#4627

Fix amend bundles appearing separately

I re-tested against elastic/elasticsearch#140795 and the content is appropriately merged, thanks!

Type-specific empty section text

I re-tested against elastic/docs-content#4843 and the text looks great now, thanks!

Other

Note that while testing the changelog directives in elastic/kibana#250840 and elastic/docs-content#4843 I re-confirmed that both the area-based and type-based blocks seem to be ineffectual. In the first case, for example, the "Elastic Observability" and "Elastic Security" areas ought to have been hidden. In the second case, the "Snapshot and restore" areas ought to be hidden.

While testing the render commands in elastic/docs-content#4627, the blocks still work, so this is just directive-specific.

It's fine to fix this in a separate PR if necessary, since it's all tied up with https://github.com/elastic/docs-eng-team/issues/403

[cotti]

@lcawl I think I got that final issue working... I have added productId as a possible parameter to the directive if it's useful, but we are now grabbing the main productId elsewhere if we can.

Yay, I added the :product: clause in elastic/kibana#250840 and it did the trick.
When I tested in elastic/docs-content#4843, it showed one remaining issue:

i.e. the "Documentation" type section was successfully hidden on the page, but still appeared in the right-hand navigation.
Ditto for the other type when I block it in elastic/elasticsearch#140795

[Mpdreamz]

--hide-features should be exposed in bundle profiles too.

I am not sure if the repo should be embedded in the bundle (can we not look this up in assemble.yml?

[cotti]

--hide-features should be exposed in bundle profiles too.

I am not sure if the repo should be embedded in the bundle (can we not look this up in assemble.yml?

Added --hide-features to the profile!

From what I understood, repo is also needed because a single changelog entry can span multiple products, but its PR only exists in one repo. So it needs to reference the origin to form the URI.

Would assembler.yml be the best place to correlate them? Is it "safe enough" for defaults? With the current feature creep in this PR, I'd vote on continuing this in a different task.