Better YAML diffs for GitOps repos

[marians]

Currently we enforce alphanumerical key sorting for YAML files, only to keep diffs in PRs minimal. This is an unexpected restriction for users, and it forces to derive from a conventional structure of Kubernetes resources.

Can we provide great diffs even if the sorting of keys changes?

[weatherhog]

@marians would something like https://github.com/homeport/dyff be a solution.

runnning dyff in a github action and posting the dyff into the PR as a comment?
The only downsinde would be, that the raw git diff stays noisy and the user would have to rely on the comment?

[marians]

The commenting is the best solution I can think of right now, and dyff is the best tool I know for this purpose.

[weatherhog]

Phased rollout in progress — phase 1 (additive infrastructure, no behaviour change) is up for review:

• feat: add yaml-diff reusable workflow github-workflows#190 — new reusable yaml-diff.yaml workflow that posts a semantic YAML diff (via dyff) of changed source files as a sticky PR comment. Key reordering without value changes is ignored. Companion to the existing helm-render-diff.yaml; shares the /no_diffs_printing opt-out.
• Add semantic YAML diff PR comments via shared workflow gitops-template#130 — adopts the new workflow on every PR. Does not yet drop key-ordering: {} from .yamllint — yamllint continues to enforce alphabetical ordering as before, the bot just adds a clean semantic-diff comment alongside.

Phase 2 (separate small PR, ~1–2 weeks after #130 is running on real PRs): drop key-ordering: {} from gitops-template/.yamllint, which will close this issue. Keeping the rule removal decoupled from the bot rollout means it's a one-line revert if anything surprises us.