Reconsider lossy YAML round-trip when editing Compose files

[scr4bble]

Summary

I would like to raise a broader concern about how Compose YAML is handled by Dockge’s structured editor.

As I understand the current implementation, Dockge parses the YAML into a document, converts it to a plain JavaScript object using doc.toJS(), and later creates a new YAML Document from that object and serializes it using doc.toString() when the structured configuration changes.

In simplified form:

original YAML text
  -> parsed YAML document
  -> plain JavaScript object
  -> new YAML document
  -> newly serialized YAML text

There is additional logic intended to copy comments into the reconstructed document, but this still appears to be a lossy YAML round trip.

My concern is that addressing individual serialization symptoms may continue to expose new edge cases, because parts of the original YAML representation are no longer available after conversion to a plain JavaScript object.

Why this matters

1. YAML semantics can change

Formatting in YAML is not always purely cosmetic.

Quotes, scalar types, leading zeroes, custom tags and other representation details can affect how Docker Compose interprets a value.

Several existing reports appear related to this broader problem:

• Quotes being stripped from stack file #486 — quotes stripped from values, including labels and timestamps
• incorrect modifications of compose.yaml for preview #906 — 0777 changed to 777
• YAML custom tags !reset and !override are parsed and substituted by Dockge instead of compose #448 — Compose-specific !reset and !override tags replaced
• Insertion of Line break within label #406 — long labels reformatted into invalid Compose YAML
• Commented out lines in compose file disappear when starting/deploying container. #176 / fix bug 176: preserve YAML comments when reordering items by matching… #685 — comments lost during document reconstruction; a partial preservation fix was added

These issues may not all have exactly the same immediate cause, but they illustrate the risks of reconstructing a Compose file rather than preserving its original YAML representation.

2. It creates noisy Git diffs

Many users keep their Compose files in Git.

When a small edit also changes unrelated formatting, quote style, blank lines, line wrapping or generated sections, the resulting diff becomes noisy. This makes the actual configuration change harder to review and increases the chance of overlooking an unintended modification.

A related example is:

• Empty "networks" section added to existing files #526 — an empty networks: {} section is added, with users also reporting removed empty lines

For Git-managed configuration, I would expect:

• a no-op save to leave the file unchanged;
• a one-field edit to change only that field;
• unrelated formatting to remain intact.

3. Symptom-specific fixes may be difficult to maintain

Comment-copying helpers and similar preservation logic can fix particular cases, but may not cover all YAML syntax supported by Compose now or introduced later.

This could result in a continuing series of issues involving:

• quoted and unquoted scalar styles;
• numeric-looking strings;
• leading zeroes;
• comments;
• blank lines;
• custom Compose tags;
• anchors and aliases;
• block scalars;
• flow versus block notation;
• line wrapping.

Suggested direction

I am not proposing a specific implementation, but I think the architectural decision may be worth reconsidering.

Possible approaches could include:

• modifying the existing parsed YAML document or AST in place instead of converting through a plain object;
• applying minimal targeted changes only to fields edited through the structured UI;
• separating the raw-text editor from the structured form editor, so raw edits are never reserialized;
• warning the user before an operation that will normalize or rewrite the complete document.

Useful regression expectations could be:

1. Opening and saving without changes produces no file diff.
2. Editing one property changes only that property.
3. Quotes, comments, blank lines, custom tags and scalar styles remain unchanged unless directly edited.
4. Tests cover quoted strings, numeric-looking strings, leading-zero values, Compose custom tags and comments between sequence items.

User impact

This rewriting behavior was the main reason I stopped using Dockge for editing my Compose stacks and moved that workflow to Arcane.

I still think Dockge has significant potential. Continued active maintenance together with non-destructive Compose editing would make me seriously consider using it again.

Would the maintainers be open to treating semantic and formatting preservation as a broader design requirement, rather than addressing only the individual serialization symptoms?