Retain initial document separator if present

[AlessandroZanatta]

Eschewed features

• This issue is not requesting templating, unstuctured edits, build-time side-effects from args or env vars, or any other eschewed feature.

What would you like to have added?

kyaml is a great library that is used by many projects. Sequence indentation retention is a very useful feature when used to automatically update YAML files (e.g. on a repository). However, it is missing a (small) piece imo, that is, retaining the initial YAML document separator (---), if present.

Why is this needed?

In projects like ArgoCD image updater or FluxCD, kyaml is used to update the images by updates to the kustomization file. While sequence indentation is retained, the initial document separator is not, thus leading to (pointless) diffs (such as this on my repository). This may additionally conflict with linter rules enforced via GitHub actions, and so on.

Can you accomplish the motivating task without this feature, and if so, how?

As far as I can tell, the library does not offer a way to do this.

What other solutions have you considered?

It would be possible to patch the projects using kyaml to add the document separator (if and when needed), but in my opinion this fits better inside the library as an optional functionality.

Anything else we should know?

I'm open to implement this change myself!

A possible implementation could be a simple (optional) boolean flag on the kio readers and writers structs that allows to retain the initial document separator, if present in the parsed document, similarly to how sequence indentation is handled currently.

Let me know if this implementation idea may work (from the point of view of clients at least), and if a contribution to implement it is appreciated.

Feature ownership

• I am interested in contributing this feature myself! 🎉

[k8s-ci-robot]

This issue is currently awaiting triage.

SIG CLI takes a lead on issue triage for this repo, but any Kubernetes member can accept issues by applying the triage/accepted label.

The triage/accepted label can be added by org members by writing /triage accepted in a comment.

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes-sigs/prow repository.