Explore: ytt being able to emit comments

[pivotaljohn]

This is a PR meant for exploration: what would be the consequences of ytt emitting comments?

Inspired by: https://hackmd.io/IqHKk9LgSkadtrhV0-qyjg

[cppforlife]

non-indented arrays is more or less a given with yaml formatting. would not be good to change that for our end users imho.

[pivotaljohn]

non-indented arrays is more or less a given with yaml formatting

From what I've seen, there is no clear consensus on the indentation of sequences:

• from the spec:

  "The amount of indentation is a presentation detail and must not be used to convey content information.

  and also notes:

  "Since people perceive the “-” indicator as indentation, nested block sequences may be indented by one less space to compensate,"

• certain communities express indentation in their guides:

  • https://developers.home-assistant.io/docs/documenting/yaml-style-guide/#block-style-sequences
  • https://github.com/flathub/flathub/wiki/YAML-Style-Guide
  • https://symfony.com/doc/current/components/yaml/yaml_format.html#:~:text=You%20can%20nest%20sequences%20and%20mappings%20as%20you%20like%3A

• eslint lints non-indented sequences as an error.

• the YAML library author weighs in as well:

  The formatting in v2 was inconsistent in several ways with many edge cases. In v3 we've changed it to simply make it not special: every depth level is indented by the space amount of spacing, regardless of its type.

  I understand that some people will be used to the old formatting, but on this basis alone it'd be hard to evolve anything.

---

... would not be good to change that for our end users imho...

I'm not sure.

On the one hand, the output of an upgraded version would not be syntactically identical, but it would semantically; so it's arguable.
One path is to give the user the option: if you want to output comments, sequences are indented; otherwise no change.

On the other hand, folks might be diff'ing text to determine if there are changes.
I'm unsure how common this is.

I'm currently thinking that the added value that comments can bring would outweigh any inconvenience.

What informs your humble opinion, here? What do you see?

[pivotaljohn]

May depend on go-yaml/yaml#749 getting addressed.

From #carvel

Yeah I think it is just that the first sperator gets removed as you can see from the example (line 2 of app.yml). I was hoping there was a way to allow this as yamllint we have checks if the --- is at the start (edited)

[pivotaljohn]

Keeping the branch, but closing this PR, for now.

[tvkit]

Allowing eslint directives would be nice:
# eslint yml/sort-keys: warn