Handle extract.release_notes properly on CI

[cotti]

Handles https://github.com/elastic/docs-eng-team/issues/490
Pre-requisite for #3015

This pull request improves how the changelog creation process handles release note extraction in CI environments, especially when using GitHub Actions. It ensures that a release note description extracted in CI is only used when extraction is enabled, and documents the precedence rules for the description field. The changes also add comprehensive tests and update the documentation for clarity.

The most important changes are:

Changelog Description Handling and Precedence:

• The CreateChangelog service now ignores any CI-provided description (from CHANGELOG_DESCRIPTION) if release note extraction is disabled either via CLI (--no-extract-release-notes) or config (extract.release_notes: false). Explicit CLI descriptions always take precedence over CI-injected ones. [1] [2] [3]
• The precedence and behavior of the CHANGELOG_DESCRIPTION environment variable are documented in both the CLI and contributor documentation, clarifying how and when the description is used or ignored. [1] [2] [3]

Testing Improvements:

• New and updated tests verify the correct behavior for all combinations of explicit CLI description, CI-provided description, and extraction enabled/disabled (both via CLI and config). This ensures the service only uses the extracted release note when appropriate. [1] [2]
• Test helpers and mocks are updated to support the new description handling logic and environment variable simulation. [1] [2] [3]

These changes make the changelog process more robust and predictable in CI, preventing accidental inclusion of extracted release notes when extraction is intentionally turned off.

[coderabbitai]

Caution

Review failed

Pull request was closed or merged during review

📝 Walkthrough

Walkthrough

The PR adds CI consumption of extracted release notes via a new description output from changelog evaluate-pr (exported as CHANGELOG_DESCRIPTION) and documents a CI two-step flow. changelog add now considers CHANGELOG_DESCRIPTION when --description is not provided and release-note extraction is enabled; if --description is passed or extraction is disabled (--no-extract-release-notes or extract.release_notes: false), the CI description is ignored. Tests and docs were updated and a computed ExtractionDisabled flag was added to creation args to drive this behavior.

Sequence Diagram

sequenceDiagram
    participant PR as GitHub PR
    participant EvalPR as changelog evaluate-pr
    participant CI as CI Environment
    participant Add as changelog add
    participant YAML as changelog.yaml

    PR->>EvalPR: Provide PR metadata (title, type, body)
    EvalPR->>EvalPR: Extract release notes (if enabled)
    EvalPR->>CI: Export CHANGELOG_TITLE, CHANGELOG_TYPE
    EvalPR->>CI: Export CHANGELOG_DESCRIPTION (when extraction produced a note)

    CI->>Add: Invoke changelog add with CHANGELOG_* env vars
    Add->>Add: Resolve description:
    Note over Add: 1) CLI `--description` wins\n2) If extraction disabled, ignore `CHANGELOG_DESCRIPTION`\n3) Else use `CHANGELOG_DESCRIPTION` when CLI blank
    Add->>YAML: Emit changelog entry with resolved fields

Loading

Suggested labels

documentation

🚥 Pre-merge checks | ✅ 2 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 5.26% 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 accurately summarizes the main change: handling release note extraction properly in CI environments, which is the core objective of this PR.
Description check	✅ Passed	The description is comprehensive and directly related to the changeset, explaining the problem, solution, and changes made across code, tests, and documentation.

_{✏️ 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 changelog/extract-fix

---

_{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 `@docs/contribute/changelog.md`:
- Line 366: The heading "CI two-step flow" is currently at h4 (####) but its
parent "Create changelog files" is h2, so change the "CI two-step flow" heading
to h3 (###) to fix the heading-level skip; locate the line containing the
heading text "CI two-step flow" in docs/contribute/changelog.md and replace the
four hashes with three so the heading sequence increments by one.

🪄 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: 085d8e6d-637f-4f7b-a478-09c2f98d894d

📥 Commits

Reviewing files that changed from the base of the PR and between 9eb637f and a82c8b9.

📒 Files selected for processing (7)

• docs/cli/changelog/add.md
• docs/cli/changelog/evaluate-pr.md
• docs/contribute/changelog.md
• src/services/Elastic.Changelog/Creation/ChangelogCreationService.cs
• tests/Elastic.Changelog.Tests/Changelogs/Create/CreateChangelogTestBase.cs
• tests/Elastic.Changelog.Tests/Changelogs/Create/ReleaseNoteExtractionTests.cs
• tests/Elastic.Changelog.Tests/Creation/CIEnrichmentTests.cs

[cotti]

Added test cases:

CreateChangelog_InCI_CliEnablesExtraction_OverridesConfigFalse_PreservesCIDescription — CLI true overrides config false. CI description is preserved because the resolved ExtractionDisabled is false after ApplyConfigDefaults keeps the CLI value via ??.

CreateChangelog_InCI_ExtractionDisabled_ExplicitCliDescription_Survives — Extraction is disabled and CI injects a description, but the explicit CLI --description survives the clearing logic. Tests the cliDescription capture in CreateChangelog that guards against the clearing block.