Changelog: Add release-date field to bundles

[cotti]

This pull request introduces support for an optional release-date field in changelog bundle YAML files. The release date is parsed, preserved through serialization and merging, and rendered in the output (Markdown and AsciiDoc) as informative, italicized text after the version heading. The feature is particularly useful for components released outside the main stack lifecycle. The implementation includes updates to documentation, data models, serialization logic, rendering, and comprehensive tests.

Key changes include:

Feature: Release Date Support in Bundles

• Added an optional release-date field to bundle YAML files, documented its usage, and updated examples in both user and syntax documentation. The field is purely informative and intended for end-users. [1] [2] [3] [4]
• Updated the Bundle and BundleDto classes to include a nullable ReleaseDate property, and ensured the property is parsed from and serialized to the YYYY-MM-DD format. [1] [2]

Serialization and Merging

• Enhanced serialization and deserialization logic to correctly handle the release-date field, including parsing from YAML, serializing to YAML, and preserving the field during bundle merging. [1] [2] [3] [4]

Rendering Enhancements

• Modified Markdown and AsciiDoc changelog renderers to display the release date (if present) immediately after the version heading, formatted as _Released: Month Day, Year_. [1] [2] [3] [4] [5]
• Updated the rendering context and service logic to support and propagate the release date, including handling cases with multiple bundles and emitting warnings if multiple differing release dates are found. [1] [2] [3] [4] [5]

Testing

• Added comprehensive unit tests to ensure correct round-trip serialization, parsing, null handling, invalid format handling, and merging behavior for the release-date field.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: edc9f9a2-a496-4139-8a55-2f6b5fcdcd4c

📥 Commits

Reviewing files that changed from the base of the PR and between 27343d2 and 224189f.

📒 Files selected for processing (2)

• docs/cli/changelog/bundle.md
• docs/syntax/changelog.md

✅ Files skipped from review due to trivial changes (2)

• docs/cli/changelog/bundle.md
• docs/syntax/changelog.md

---

📝 Walkthrough

Walkthrough

This PR adds an optional top-level release-date field for changelog bundle YAML. The field is serialized/deserialized as release-date in DTOs, parsed as DateOnly? (accepting yyyy-MM-dd), merged across bundles with deduplication (warn/omit if multiple distinct dates), and threaded into render contexts. Markdown and Asciidoc renderers output an italic _Released: {date}_ line immediately after the ## {version} heading. Documentation and tests were added to cover serialization, merging, parsing, and rendering behavior.

Sequence Diagram(s)

sequenceDiagram
    participant YAML as Bundle YAML
    participant Loader as BundleLoader
    participant Ser as ReleaseNotesSerialization
    participant DTO as BundleDto
    participant Model as Bundle
    participant Merger as MergeBundleGroup
    participant Service as ChangelogRenderingService
    participant Context as ChangelogRenderContext
    participant Renderer as Markdown/Asciidoc Renderer
    participant Output

    YAML->>Loader: Load bundle files
    Loader->>Ser: Deserialize into BundleDto
    Ser->>Model: Parse dto.ReleaseDate -> Bundle.ReleaseDate (DateOnly?)
    Loader->>Merger: Merge bundles for same target
    Merger->>Model: Aggregate distinct ReleaseDate values (dedupe)
    Service->>Model: Collect bundle ReleaseDate(s)
    Service->>Service: Validate distinct dates (warn if >1)
    Service->>Context: Build ChangelogRenderContext(BundleReleaseDate)
    Context->>Renderer: Render with BundleReleaseDate
    Renderer->>Output: Emit "## {version}" then blank line + "_Released: {date}_" then content

Loading

Suggested labels

documentation

🚥 Pre-merge checks | ✅ 2 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 10.34% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title 'Changelog: Add release-date field to bundles' accurately and concisely describes the primary change in the PR: introducing a new optional release-date field to bundle YAML files.
Description check	✅ Passed	The description comprehensively relates to the changeset, detailing the feature introduction, serialization/deserialization enhancements, rendering updates, and testing additions across all modified files.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

✨ Simplify code

• Create PR with simplified code
• Commit simplified code in branch bundle-release-date

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@src/services/Elastic.Changelog/Rendering/ChangelogRenderingService.cs`:
- Around line 155-171: The code treats identical release dates from multiple
bundles as a conflict because bundleReleaseDates uses raw values; update the
logic to deduplicate the extracted dates (from validationResult.Bundles ->
bundleReleaseDates) before checking Count (e.g., replace the ToList() with a
distinct collection or call .Distinct() and then ToList()), then use the single
unique value to set renderReleaseDate or emit the warning via
collector.EmitWarning only when more than one distinct release date remains.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 0b3231e0-35a4-4d22-ba88-2e9a1722b9cf

📥 Commits

Reviewing files that changed from the base of the PR and between 75fc1d6 and 1a78ddf.

📒 Files selected for processing (13)

• docs/cli/changelog/bundle.md
• docs/syntax/changelog.md
• src/Elastic.Documentation.Configuration/ReleaseNotes/Bundle.cs
• src/Elastic.Documentation.Configuration/ReleaseNotes/BundleLoader.cs
• src/Elastic.Documentation.Configuration/ReleaseNotes/ReleaseNotesSerialization.cs
• src/Elastic.Documentation/ReleaseNotes/Bundle.cs
• src/Elastic.Markdown/Myst/Directives/Changelog/ChangelogInlineRenderer.cs
• src/services/Elastic.Changelog/Rendering/Asciidoc/ChangelogAsciidocRenderer.cs
• src/services/Elastic.Changelog/Rendering/ChangelogRenderContext.cs
• src/services/Elastic.Changelog/Rendering/ChangelogRenderingService.cs
• src/services/Elastic.Changelog/Rendering/Markdown/IndexMarkdownRenderer.cs
• tests/Elastic.Changelog.Tests/Changelogs/BundleLoading/BundleLoaderTests.cs
• tests/Elastic.Markdown.Tests/Directives/ChangelogBasicTests.cs

[lcawl]

It looks like this PR implements the rendering of the date but not the addition? I think in a follow-up PR we should add a command option (or else have it automatically set for all bundles and an option in the config file to show/hide it)?

Here's my PR where I've drafted those enhancements: #3072

[lcawl]

Docs LGTM. I tested against elastic/elastic-otel-java#1046 and it rendered the output successfully above the description:

[Mpdreamz]

LGTM, I think we should always set it automatically when calling bundle command too?

[Mpdreamz]

Just spotted @lcawl follow up PR :)