From 4fc3f0e6f6b93cebe591a22e9b4d514f599c2520 Mon Sep 17 00:00:00 2001 From: Sebastiaan van Stijn Date: Mon, 10 Jul 2023 20:18:28 +0200 Subject: [PATCH] search: deprecate "is-automated" filter and "IsAutomated" field The IsAutomated field is being deprecated by Docker Hub's search API and will always be "false" in future. This patch: - Deprecates the field and the related "is-automated" filter - Removes the "AUTOMATED" column from the default output of "docker search" Signed-off-by: Sebastiaan van Stijn --- cli/command/registry/formatter_search.go | 9 +- cli/command/registry/formatter_search_test.go | 4 +- cli/command/registry/search.go | 4 + .../search-context-write-stars-table.golden | 4 +- .../search-context-write-table.golden | 6 +- docs/deprecated.md | 16 +++ docs/reference/commandline/search.md | 109 ++++++++---------- man/src/search.md | 19 +-- 8 files changed, 83 insertions(+), 88 deletions(-) diff --git a/cli/command/registry/formatter_search.go b/cli/command/registry/formatter_search.go index 4dc3c657e2..7d3f55b4d4 100644 --- a/cli/command/registry/formatter_search.go +++ b/cli/command/registry/formatter_search.go @@ -9,7 +9,7 @@ import ( ) const ( - defaultSearchTableFormat = "table {{.Name}}\t{{.Description}}\t{{.StarCount}}\t{{.IsOfficial}}\t{{.IsAutomated}}" + defaultSearchTableFormat = "table {{.Name}}\t{{.Description}}\t{{.StarCount}}\t{{.IsOfficial}}" starsHeader = "STARS" officialHeader = "OFFICIAL" @@ -19,9 +19,7 @@ const ( // NewSearchFormat returns a Format for rendering using a network Context func NewSearchFormat(source string) formatter.Format { switch source { - case "": - return defaultSearchTableFormat - case formatter.TableFormatKey: + case "", formatter.TableFormatKey: return defaultSearchTableFormat } return formatter.Format(source) @@ -95,6 +93,9 @@ func (c *searchContext) IsOfficial() string { return c.formatBool(c.s.IsOfficial) } +// IsAutomated formats the IsAutomated field for printing. +// +// Deprecated: the "is_automated" field is deprecated and will always be "false" in the future. func (c *searchContext) IsAutomated() string { return c.formatBool(c.s.IsAutomated) //nolint:staticcheck // ignore SA1019 (IsAutomated is deprecated). } diff --git a/cli/command/registry/formatter_search_test.go b/cli/command/registry/formatter_search_test.go index c518f908f4..53d9f01e18 100644 --- a/cli/command/registry/formatter_search_test.go +++ b/cli/command/registry/formatter_search_test.go @@ -50,13 +50,13 @@ func TestSearchContext(t *testing.T) { s: registrytypes.SearchResult{IsAutomated: true}, //nolint:staticcheck // ignore SA1019 (IsAutomated is deprecated). }, expValue: "[OK]", - call: ctx.IsAutomated, + call: ctx.IsAutomated, //nolint:staticcheck // ignore SA1019 (IsAutomated is deprecated). }, { searchCtx: searchContext{ s: registrytypes.SearchResult{}, }, - call: ctx.IsAutomated, + call: ctx.IsAutomated, //nolint:staticcheck // ignore SA1019 (IsAutomated is deprecated). }, } diff --git a/cli/command/registry/search.go b/cli/command/registry/search.go index 86e3ae91e5..c2f78dfce1 100644 --- a/cli/command/registry/search.go +++ b/cli/command/registry/search.go @@ -2,6 +2,7 @@ package registry import ( "context" + "fmt" "github.com/docker/cli/cli" "github.com/docker/cli/cli/command" @@ -49,6 +50,9 @@ func NewSearchCommand(dockerCli command.Cli) *cobra.Command { } func runSearch(dockerCli command.Cli, options searchOptions) error { + if options.filter.Value().Contains("is-automated") { + _, _ = fmt.Fprintln(dockerCli.Err(), `WARNING: the "is-automated" filter is deprecated, and searching for "is-automated=true" will not yield any results in future.`) + } indexInfo, err := registry.ParseSearchIndexInfo(options.term) if err != nil { return err diff --git a/cli/command/registry/testdata/search-context-write-stars-table.golden b/cli/command/registry/testdata/search-context-write-stars-table.golden index 1a66b42927..51686c79ee 100644 --- a/cli/command/registry/testdata/search-context-write-stars-table.golden +++ b/cli/command/registry/testdata/search-context-write-stars-table.golden @@ -1,2 +1,2 @@ -NAME DESCRIPTION STARS OFFICIAL AUTOMATED -result1 Official build 5000 [OK] +NAME DESCRIPTION STARS OFFICIAL +result1 Official build 5000 [OK] diff --git a/cli/command/registry/testdata/search-context-write-table.golden b/cli/command/registry/testdata/search-context-write-table.golden index 952ae79789..d183794427 100644 --- a/cli/command/registry/testdata/search-context-write-table.golden +++ b/cli/command/registry/testdata/search-context-write-table.golden @@ -1,3 +1,3 @@ -NAME DESCRIPTION STARS OFFICIAL AUTOMATED -result1 Official build 5000 [OK] -result2 Not official 5 [OK] +NAME DESCRIPTION STARS OFFICIAL +result1 Official build 5000 [OK] +result2 Not official 5 diff --git a/docs/deprecated.md b/docs/deprecated.md index 0e257584be..b16dd15437 100644 --- a/docs/deprecated.md +++ b/docs/deprecated.md @@ -50,6 +50,7 @@ The table below provides an overview of the current status of deprecated feature | Status | Feature | Deprecated | Remove | |------------|------------------------------------------------------------------------------------------------------------------------------------|------------|--------| +| Deprecated | [IsAutomated field, and "is-automated" filter on docker search](#isautomated-field--and-is--automated-filter-on-docker-search) | v25.0 | - | | Deprecated | [OOM-score adjust for the daemon](#oom-score-adjust-for-the-daemon) | v24.0 | v25.0 | | Removed | [Buildkit build information](#buildkit-build-information) | v23.0 | v24.0 | | Deprecated | [Legacy builder for Linux images](#legacy-builder-for-linux-images) | v23.0 | - | @@ -106,6 +107,21 @@ The table below provides an overview of the current status of deprecated feature | Removed | [`--run` flag on `docker commit`](#--run-flag-on-docker-commit) | v0.10 | v1.13 | | Removed | [Three arguments form in `docker import`](#three-arguments-form-in-docker-import) | v0.6.7 | v1.12 | + +### IsAutomated field, and "is-automated" filter on docker search + +**Deprecated in Release: v25.0** +**Target For Removal In Release: v26.0** + +The "is_automated" field has been deprecated by Docker Hub's search API. +Consequently, the `IsAutomated` field in image search will always be set +to `false` in future, and searching for "is-automated=true" will yield no +results. + +The `AUTOMATED` column has been removed from the default `docker search` +and `docker image search` output in v25.0, and the corresponding `IsAutomated` +templating option will be removed in v26.0. + ### OOM-score adjust for the daemon **Deprecated in Release: v24.0** diff --git a/docs/reference/commandline/search.md b/docs/reference/commandline/search.md index db073e6135..0e1b5a73f4 100644 --- a/docs/reference/commandline/search.md +++ b/docs/reference/commandline/search.md @@ -28,31 +28,31 @@ This example displays images with a name containing 'busybox': ```console $ docker search busybox -NAME DESCRIPTION STARS OFFICIAL AUTOMATED +NAME DESCRIPTION STARS OFFICIAL busybox Busybox base image. 316 [OK] -progrium/busybox 50 [OK] -radial/busyboxplus Full-chain, Internet enabled, busybox made... 8 [OK] -odise/busybox-python 2 [OK] -azukiapp/busybox This image is meant to be used as the base... 2 [OK] -ofayau/busybox-jvm Prepare busybox to install a 32 bits JVM. 1 [OK] -shingonoide/archlinux-busybox Arch Linux, a lightweight and flexible Lin... 1 [OK] -odise/busybox-curl 1 [OK] -ofayau/busybox-libc32 Busybox with 32 bits (and 64 bits) libs 1 [OK] -peelsky/zulu-openjdk-busybox 1 [OK] -skomma/busybox-data Docker image suitable for data volume cont... 1 [OK] -elektritter/busybox-teamspeak Lightweight teamspeak3 container based on... 1 [OK] -socketplane/busybox 1 [OK] -oveits/docker-nginx-busybox This is a tiny NginX docker image based on... 0 [OK] -ggtools/busybox-ubuntu Busybox ubuntu version with extra goodies 0 [OK] -nikfoundas/busybox-confd Minimal busybox based distribution of confd 0 [OK] -openshift/busybox-http-app 0 [OK] -jllopis/busybox 0 [OK] -swyckoff/busybox 0 [OK] -powellquiring/busybox 0 [OK] -williamyeh/busybox-sh Docker image for BusyBox's sh 0 [OK] -simplexsys/busybox-cli-powered Docker busybox images, with a few often us... 0 [OK] -fhisamoto/busybox-java Busybox java 0 [OK] -scottabernethy/busybox 0 [OK] +progrium/busybox 50 +radial/busyboxplus Full-chain, Internet enabled, busybox made... 8 +odise/busybox-python 2 +azukiapp/busybox This image is meant to be used as the base... 2 +ofayau/busybox-jvm Prepare busybox to install a 32 bits JVM. 1 +shingonoide/archlinux-busybox Arch Linux, a lightweight and flexible Lin... 1 +odise/busybox-curl 1 +ofayau/busybox-libc32 Busybox with 32 bits (and 64 bits) libs 1 +peelsky/zulu-openjdk-busybox 1 +skomma/busybox-data Docker image suitable for data volume cont... 1 +elektritter/busybox-teamspeak Lightweight teamspeak3 container based on... 1 +socketplane/busybox 1 +oveits/docker-nginx-busybox This is a tiny NginX docker image based on... 0 +ggtools/busybox-ubuntu Busybox ubuntu version with extra goodies 0 +nikfoundas/busybox-confd Minimal busybox based distribution of confd 0 +openshift/busybox-http-app 0 +jllopis/busybox 0 +swyckoff/busybox 0 +powellquiring/busybox 0 +williamyeh/busybox-sh Docker image for BusyBox's sh 0 +simplexsys/busybox-cli-powered Docker busybox images, with a few often us... 0 +fhisamoto/busybox-java Busybox java 0 +scottabernethy/busybox 0 marclop/busybox-solr ``` @@ -64,10 +64,10 @@ at least 3 stars and the description isn't truncated in the output: ```console $ docker search --filter=stars=3 --no-trunc busybox -NAME DESCRIPTION STARS OFFICIAL AUTOMATED +NAME DESCRIPTION STARS OFFICIAL busybox Busybox base image. 325 [OK] -progrium/busybox 50 [OK] -radial/busyboxplus Full-chain, Internet enabled, busybox made from scratch. Comes in git and cURL flavors. 8 [OK] +progrium/busybox 50 +radial/busyboxplus Full-chain, Internet enabled, busybox made from scratch. Comes in git and cURL flavors. 8 ``` ### Limit search results (--limit) @@ -78,12 +78,12 @@ value is set, the default is set by the daemon. ### Filtering (--filter) The filtering flag (`-f` or `--filter`) format is a `key=value` pair. If there is more -than one filter, then pass multiple flags (e.g. `--filter is-automated=true --filter stars=3`) +than one filter, then pass multiple flags (e.g. `--filter is-official=true --filter stars=3`) The currently supported filters are: - stars (int - number of stars the image has) -- is-automated (boolean - true or false) - is the image automated or not +- is-automated (boolean - true or false) - is the image automated or not (deprecated) - is-official (boolean - true or false) - is the image official or not #### stars @@ -94,23 +94,10 @@ least 3 stars: ```console $ docker search --filter stars=3 busybox -NAME DESCRIPTION STARS OFFICIAL AUTOMATED +NAME DESCRIPTION STARS OFFICIAL busybox Busybox base image. 325 [OK] -progrium/busybox 50 [OK] -radial/busyboxplus Full-chain, Internet enabled, busybox made... 8 [OK] -``` - -#### is-automated - -This example displays images with a name containing 'busybox' -and are automated builds: - -```console -$ docker search --filter is-automated=true busybox - -NAME DESCRIPTION STARS OFFICIAL AUTOMATED -progrium/busybox 50 [OK] -radial/busyboxplus Full-chain, Internet enabled, busybox made... 8 [OK] +progrium/busybox 50 +radial/busyboxplus Full-chain, Internet enabled, busybox made... 8 ``` #### is-official @@ -121,7 +108,7 @@ This example displays images with a name containing 'busybox', at least ```console $ docker search --filter is-official=true --filter stars=3 busybox -NAME DESCRIPTION STARS OFFICIAL AUTOMATED +NAME DESCRIPTION STARS OFFICIAL busybox Busybox base image. 325 [OK] ``` @@ -132,13 +119,13 @@ using a Go template. Valid placeholders for the Go template are: -| Placeholder | Description | -|----------------|-----------------------------------| -| `.Name` | Image Name | -| `.Description` | Image description | -| `.StarCount` | Number of stars for the image | -| `.IsOfficial` | "OK" if image is official | -| `.IsAutomated` | "OK" if image build was automated | +| Placeholder | Description | +|----------------|------------------------------------------------| +| `.Name` | Image Name | +| `.Description` | Image description | +| `.StarCount` | Number of stars for the image | +| `.IsOfficial` | "OK" if image is official | +| `.IsAutomated` | "OK" if image build was automated (deprecated) | When you use the `--format` option, the `search` command will output the data exactly as the template declares. If you use the @@ -165,13 +152,13 @@ maxexcloo/nginx: 7 This example outputs a table format: ```console -$ docker search --format "table {{.Name}}\t{{.IsAutomated}}\t{{.IsOfficial}}" nginx +$ docker search --format "table {{.Name}}\t{{.IsOfficial}}" nginx -NAME AUTOMATED OFFICIAL -nginx [OK] -jwilder/nginx-proxy [OK] -richarvey/nginx-php-fpm [OK] -jrcs/letsencrypt-nginx-proxy-companion [OK] -million12/nginx-php [OK] -webdevops/php-nginx [OK] +NAME OFFICIAL +nginx [OK] +jwilder/nginx-proxy +richarvey/nginx-php-fpm +jrcs/letsencrypt-nginx-proxy-companion +million12/nginx-php +webdevops/php-nginx ``` diff --git a/man/src/search.md b/man/src/search.md index 6caf4ad2ea..52e593828b 100644 --- a/man/src/search.md +++ b/man/src/search.md @@ -6,7 +6,7 @@ of stars awarded, whether the image is official, and whether it is automated. Filter output based on these conditions: - stars= - - is-automated=(true|false) + - is-automated=(true|false) (deprecated) - is-official=(true|false) # EXAMPLES @@ -17,18 +17,5 @@ Search a registry for the term 'fedora' and only display those images ranked 3 or higher: $ docker search --filter=stars=3 fedora - NAME DESCRIPTION STARS OFFICIAL AUTOMATED - mattdm/fedora A basic Fedora image corresponding roughly... 50 - fedora (Semi) Official Fedora base image. 38 - mattdm/fedora-small A small Fedora image on which to build. Co... 8 - goldmann/wildfly A WildFly application server running on a ... 3 [OK] - -## Search Docker Hub for automated images - -Search Docker Hub for the term 'fedora' and only display automated images -ranked 1 or higher: - - $ docker search --filter=is-automated=true --filter=stars=1 fedora - NAME DESCRIPTION STARS OFFICIAL AUTOMATED - goldmann/wildfly A WildFly application server running on a ... 3 [OK] - tutum/fedora-20 Fedora 20 image with SSH access. For the r... 1 [OK] + NAME DESCRIPTION STARS OFFICIAL + fedora Official Docker builds of Fedora 1150 [OK]