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/<version>.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
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.
Summary
The
validateChangelogsschema check inelastic/elasticsearchrejects markdown code blocks in per-PR changelog YAMLs underdocs/changelog/, even though the docs site renders them correctly.The validator still requires Asciidoc-style blocks (
[source,xxx] / ----) inhighlightanddetailsfields, 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/<version>.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.bodyand `details` fields of per-PR changelog YAMLs, matching what the docs site already renders.Actual behavior
./gradlew precommitfails on per-PR YAMLs containing triple-backtickblocks with:
Reproduction
See
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 indocs-content:build-tools-internal/src/main/resources/changelog-schema.jsonValidateYamlAgainstSchemaTask, wired up inReleaseToolsPlugin.javaasvalidateChangelogsprecommitGradle task in CIThe schema currently has a rule that flags triple-backticks in
highlight.bodyanddetails.Impact
Docs writers can't fix or improve code snippets in already-merged changelog entries without either:
bundleChangelogs --finalizeoverwrites pre-release bundles).Possible contact
Brian Seeders for the build-tools side.