elastic / elastic/docs-content
Update `validateChangelogs` schema to accept markdown code blocks in per-PR changelog YAMLs
- 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.