changelog generated yaml utf8 BOM

[SylvainJuge]

The YAML generated by docs-builder changelog starts with an UTF-8 BOM (Byte Order Mark) which may make some tools fail to handle this properly as reported by Copilot here.

I think we should clarify the following:

• is this BOM usage intentional for the generated yaml, for example to help with localization of content or integration with other tooling
• if the potential issue reported by copilot is significant or not in practice, if not, then we should find a way to avoid such noisy comments.

There are two possible approaches depending on the answer to the questions above:

• if it's not intentional nor needed, then we can just remove it as it's simpler
• if it's intentional or required, then we should find a way to make copilot (and others) stop from reporting it as a potential issue.

In practice, the impact of this is minor but not zero because it's mostly noise on the PR reviewer. However it also makes the copilot (or similar) automated review less useful for changelog-related PRs, which keeps some friction in the release process.

[lcawl]

Based on AI analysis:

Code inspection: Changelog YAML from serialization is written with Encoding.UTF8 and File.WriteAllTextAsync(...), which in current .NET is UTF-8 without a BOM. YamlDotNet only returns a string; it does not emit a BOM. There is no new UTF8Encoding(true) (BOM-on) usage in changelog paths. Templates and scanned fixtures checked in-repo had no BOM.

Implication: The BOM is not an intentional product feature (not for localization or interoperability). If it appears in PRs, likely sources are byte-preserving steps (File.Copy, uploads), editor saves after generation, or another tool in the pipeline—not a deliberate docs-builder design...

Verify: Add tests that assert written changelog YAML / bundle files do not start with UTF-8 BOM bytes (and optionally that BOM-prefixed inputs normalize to BOM-free outputs). Optionally run a one-off local changelog add / bundle smoke and hex-dump first bytes for PR evidence if integration repro remains elusive.

Solution

Normalize: Small Elastic.Changelog helper: strip leading U+FEFF from strings; optionally ReadOnlySpan check for EF BB BF. Prefer new UTF8Encoding(encoderShouldEmitUTF8Identifier: false) (or document equivalence to Encoding.UTF8) at a single internal “write YAML text” helper if that reduces duplicated encoding assumptions—without expanding scope to unrelated projects.

Byte-preserving paths: Where changelog YAML is copied verbatim, switch to read → strip BOM from text → write UTF-8 no BOM for that file type only.