elastic / elastic/docs-content

Update `validateChangelogs` schema to accept markdown code blocks in per-PR changelog YAMLs

Open
#6,343 2 comments 0 reactions 1 assignee Claimed by @charlotte-hoblik View on GitHub
documentation release-notes Team:Developer
Dominant language
No language data
Stars
47
Forks
261
Avg merge
3d 12h
Merged PRs (30d)
116

Description

## Summary

The `validateChangelogs` schema check in `elastic/elasticsearch` rejects markdown code blocks in per-PR changelog YAMLs under `docs/changelog/`, even though the docs site renders them correctly.
The validator still requires Asciidoc-style blocks (`[source,xxx] / ----`) in `highlight` and `details` fields, which is inconsistent with the rest of the markdown-based docs platform.

The same validator does *not* run against the version bundle files in `docs/release-notes/changelog-bundles/.yml`, so markdown works there — but bundles are regenerated on every finalize, which makes that an unreliable workaround for unreleased versions.

## Expected behavior

Markdown code blocks (```) should be valid in `highlight.body` and `details` fields of per-PR changelog YAMLs, matching what the docs site already renders.

## Actual behavior

`./gradlew precommit` fails on per-PR YAMLs containing triple-backtick
blocks with:

> [validate YAML][ERROR][.yaml][Changelog uses a triple-backtick (```)
> in a details section, but it must be formatted as a Asciidoc code block.

## Reproduction

See
- https://github.com/elastic/elasticsearch/pull/146212
- https://buildkite.com/elastic/elasticsearch-pull-request/builds/142603
- https://github.com/elastic/elasticsearch/pull/147307

Converted several per-PR YAMLs from Asciidoc to markdown code blocks; CI rejected the change with the error above.
## Where the fix lives

The validator is in `elastic/elasticsearch`, not in `docs-content`:

- Schema: `build-tools-internal/src/main/resources/changelog-schema.json`
- Task: `ValidateYamlAgainstSchemaTask`, wired up in `ReleaseToolsPlugin.java` as `validateChangelogs`
- Runs as a dependency of the `precommit` Gradle task in CI

The schema currently has a rule that flags triple-backticks in `highlight.body` and `details`.

## Impact

Docs writers can't fix or improve code snippets in already-merged changelog entries without either:
- using Asciidoc form that's inconsistent with the rest of the docs source, or
- editing the bundle YAML directly (only safe post-release, since `bundleChangelogs --finalize` overwrites pre-release bundles).

## Possible contact

Brian Seeders for the build-tools side.

Contributor guide

No contributing guide indexed for this repository

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.