v1 and v2 are very different: clarity required in Marketplace

First, I’ll preface this issue: I really like the improvements made to the action with the switch to buildx, I think @crazy-max has done great work, I’m now using v2 and intend to continue doing so! The re-focus of the action around being the build step with delegation to other packages for things like login is great, it is a great step forward.

That said, I’m a little concerned that v2 is now the default. v1 of this action and v2 are very different, the philosophy has changed: v1 does everything you need and could be your entire workflow. That change alone wouldn’t be of huge concern if it was clearly documented and a migration path was provided, but on top of changing the philosophy of the action the underlying technology has changed (build -> buildx). buildx is identified as “an experimental feature”, “Tech Preview”[1] and “[…] must not be used in production environments”[2] but docker/build-push-action is the GitHub action to use as part of a dockerised application’s GitHub Workflow.

(My own experience: I’ve run into quite a few issues using buildx in a GitHub Workflow, which I’ve been able to resolve through investigation and experimentation, but it’s definitely not yet ready within the GitHub ecosystem as a drop-in replacement for build)

There are a few different use-cases for this action, but the ~two~ three that I think are most important when considering a change like this are:

1. Projects already using this action in their workflows – there are thousands of projects that are using @v1 but they’ll be unable to find the documentation for it unless they understand the way to access old versions via the Marketplace i. bonus consideration: Lots of people learn about how to build their own Workflows by looking at examples from open source projects
2. Tutorials, guides and documentation across the internet referring to v1 and describing the behaviour that is no longer supported, e.g: First Docker GitHub Action is here!
3. Projects that cannot use the new functionality (buildx)

If you visit the marketplace page for v1 and compare it to the current marketplace page there is no recognition of the significant change.

https://github.com/marketplace/actions/build-and-push-docker-images?version=v1.0.0 https://github.com/marketplace/actions/build-and-push-docker-images

As I see it there are 2 options:

1. Modify the README on master so it makes very clear that there is an @v1 and @v2 that behave differently, that they’re effectively different actions and users need to make an active decision between which version they wish to use – @v2 is not suitable for production use at companies where documented limitations must be respected.

2. Split v2 into a separate action (e.g: docker/buildx-push-action) and restore this action to v1.

I think that option 2 is the right choice because there is value in both @v1 (build) and @v2 (buildx) over the long term but at a minimum updating the documentation to provide clarity to all (new, existing) users is required. I’m happy to PR improvements to the documentation but I’m not sure if there are strong views in favour of option 2 so I’m sharing my thoughts for discussion first 😃

Thanks,

[1] https://docs.docker.com/buildx/working-with-buildx/

Experimental features provide early access to future product functionality. These features are intended for testing and feedback only as they may change between releases without warning or can be removed entirely from a future release. Experimental features must not be used in production environments. Docker does not offer support for experimental features.

[2] https://github.com/docker/buildx

[crazy-max]

@shrink Following our meeting last week, upgrade notes and a dedicated section on top of the README have been added. We are also going to add some explanations around the builder driver used with setup-buildx-action.

[nebuk89]

@shrink thank you for the feedback! this is really well thought out and put, we will discuss and get back to you