feat: add confirmation label when volume spec changes

[qianlongzt]

What I did

Add support for label: com.docker.compose.volume.recreate-when-spec-updated

volumes:
  my_data:
    labels:
      com.docker.compose.volume.recreate-when-spec-updated: "true"

This allows automatic handling of volume recreation when specs change, improving compatibility with CD workflows by avoiding interactive prompts.

Related issue

closes: #13807

(not mandatory) A picture of a cute animal, if possible in relation to what you did

[Quantum0uasar]

This is a useful feature for CD pipeline automation — the interactive volume recreation prompt is a common friction point in CI/CD environments. A few thoughts on the implementation:

Label naming convention

com.docker.compose.volume.recreate-when-spec-updated follows the existing Docker label namespace convention well. However, consider whether a shorter, more ergonomic alias like com.docker.compose.recreate=on-spec-change would be easier to remember. Looking at the existing Compose label space, verbose names are the norm, so the proposed name is consistent.

Scope: volumes only, or also other resources?

The same "recreate on spec change" problem applies to networks (e.g., network subnet changes) and potentially configs/secrets. While it's fine to scope this PR to volumes only, it would be worth noting in the PR description whether this label pattern is intended to be extensible to other resource types in the future, or if it's intentionally volume-specific.

Safety consideration: data loss risk

Reproducing a named volume destroys existing data. The label effectively silences a prompt that exists specifically to prevent accidental data loss. The implementation should clearly document this in:

1. The label's inline comment in the code
2. The Compose spec documentation (reference docs for labels)
3. Potentially a warning logged to stderr even when the label is set (e.g., WARN: Volume 'mydata' is being recreated due to spec change (label: com.docker.compose.volume.recreate-when-spec-updated)) so operators have an audit trail

CI workflow example

A concrete usage example in the PR description would help reviewers understand the target use case:

volumes:
  my_data:
    labels:
      com.docker.compose.volume.recreate-when-spec-updated: "true"

This makes it immediately clear whether the label value matters (boolean string) or just the presence of the label key is sufficient.

Good feature for automation-first workflows. The main thing I'd want to see before merge is explicit data-loss documentation.

[qianlongzt]

I checked the code and couldn't find any other resource types that currently support this kind of recreation behavior. Because of that, I'd prefer to keep the scope limited to volumes for now.

I'm also not a big fan of a value-based label such as com.docker.compose.recreate=on-spec-change.

At the moment, the behavior is essentially a yes/no decision, similar to how the --yes flag works. A boolean-style label seems simpler and easier to understand. If we introduce additional recreation policies in the future, we can revisit the label format then.

[qianlongzt]

@Quantum0uasar I updated the code comments and added warning logs to show what will happen when the volume spec changes. But I couldn't find where to add the documentation. Should I add it to docs/reference/compose_up.md?

[vaguul]

Thanks for adding the PR and tests. One edge case I would check before this moves forward: the current patch calls confirmVolumeRecreate(inspected.Volume.Labels, ...), so the decision is based on the labels already stored on the existing Docker volume, not the labels from the Compose file being applied.

That means these two cases can behave unexpectedly:

• old file has no recreate label, new file adds it: Compose still prompts because the existing volume does not have the label yet
• old file has the label, new file removes it or sets it false: Compose may still auto-recreate because the existing volume still has the old label

A useful regression test would be old.yml without com.docker.compose.volume.recreate-when-spec-updated, then new.yml with that label set to true. If the intended policy is controlled by the desired Compose spec, the recreate decision probably needs to use the desired volume.Labels rather than inspected.Volume.Labels.

Small secondary point: if the label is present with an invalid or false-ish value, it currently skips the prompt and returns false. If the label is only meant to opt in to auto-confirm, false/invalid values may be safer as normal prompt behavior instead of silently changing the decision.

[qianlongzt]

@vaguul I updated it to use a Docker Compose volume label and prompt the user for confirmation when the label is set to false.

[vaguul]

Thanks for updating it. The current version addresses the edge case I was worried about: confirmVolumeRecreate(volume.Labels, ...) now uses the desired Compose spec labels, and the new e2e case covers the old-file-without-label -> new-file-with-label path.\n\nI also like that false/no-label now falls back to the existing prompt behavior instead of silently changing the decision. From my side, this looks much safer.