Show Devfile Stack versions in "odo registry" output (#6397)

* Make the registry client collect and return all stack versions

* Call the '/v2index' endpoint first and fallback to the index endpoint when listing Stack versions

* Display the Stack versions in the 'odo registry' human-readable output

* For convenience, sort stack versions based on the semantic version

This allows seeing them in a meaningful order in both
human-readable and JSON outputs.

* Enrich unit tests for 'getRegistryStacks'

* Fill the "starterProjects" field for backward compatibility

Similar to the "version" field, this represents
the list of starter projects of the default Stack version.

* Update integration tests

* Update documentation

docs/website/docs/command-reference/json-output.md

@@ -314,69 +314,106 @@ odo registry -o json
 ```
 ```json
 [
-	{
-		"name": "python-django",
-		"displayName": "Django",
-		"description": "Python3.7 with Django",
-		"registry": {
-			"name": "DefaultDevfileRegistry",
-			"url": "https://registry.devfile.io",
-			"secure": false
-		},
-		"language": "python",
-		"tags": [
-			"Python",
-			"pip",
-			"Django"
-		],
-		"projectType": "django",
-		"version": "1.0.0",
-		"starterProjects": [
-			"django-example"
-		]
-	}, [...]
+  {
+    "name": "python",
+    "displayName": "Python",
+    "description": "Python is an interpreted, object-oriented, high-level programming language with dynamic semantics. Its high-level built in data structures, combined with dynamic typing and dynamic binding, make it very attractive for Rapid Application Development, as well as for use as a scripting or glue language to connect existing components together.",
+    "registry": {
+      "name": "DefaultDevfileRegistry",
+      "url": "https://registry.devfile.io",
+      "secure": false
+    },
+    "language": "Python",
+    "tags": [
+      "Python",
+      "Pip",
+      "Flask"
+    ],
+    "projectType": "Python",
+    "version": "2.1.0",
+    "versions": [
+      {
+        "version": "2.1.0",
+        "isDefault": true,
+        "schemaVersion": "2.1.0",
+        "starterProjects": [
+          "flask-example"
+        ]
+      },
+      {
+        "version": "3.0.0",
+        "isDefault": false,
+        "schemaVersion": "2.2.0",
+        "starterProjects": [
+          "flask-example"
+        ]
+      }
+    ],
+    "starterProjects": [
+      "flask-example"
+    ]
+  },
+  [...]
 ]
 ```
 
 Using the `--details` flag, you will also get information about the Devfile:
 
 ```shell
-odo registry --details -o json
+odo registry --devfile java-springboot --details -o json
 ```
 ```json
 [
-	{
-		"name": "python-django",
-		"displayName": "Django",
-		"description": "Python3.7 with Django",
-		"registry": {
-			"name": "DefaultDevfileRegistry",
-			"url": "https://registry.devfile.io",
-			"secure": false
-		},
-		"language": "python",
-		"tags": [
-			"Python",
-			"pip",
-			"Django"
-		],
-		"projectType": "django",
-		"version": "1.0.0",
-		"starterProjects": [
-			"django-example"
-		],
-		"devfileData": {
-			"devfile": {
-				"schemaVersion": "2.0.0",
-				[ devfile.yaml file content ]
-			},
-			"supportedOdoFeatures": {
-				"dev": true,
-				"deploy": false,
-				"debug": true
-			}
-		},
-	}, [...]
+  {
+    "name": "java-springboot",
+    "displayName": "Spring Boot",
+    "description": "Spring Boot using Java",
+    "registry": {
+      "name": "DefaultDevfileRegistry",
+      "url": "https://registry.devfile.io",
+      "secure": false
+    },
+    "language": "Java",
+    "tags": [
+      "Java",
+      "Spring Boot"
+    ],
+    "projectType": "springboot",
+    "version": "1.2.0",
+    "versions": [
+      {
+        "version": "1.2.0",
+        "isDefault": true,
+        "schemaVersion": "2.1.0",
+        "starterProjects": [
+          "springbootproject"
+        ]
+      },
+      {
+        "version": "2.0.0",
+        "isDefault": false,
+        "schemaVersion": "2.2.0",
+        "starterProjects": [
+          "springbootproject"
+        ]
+      }
+    ],
+    "starterProjects": [
+      "springbootproject"
+    ],
+    "devfileData": {
+      "devfile": {
+        "schemaVersion": "2.0.0",
+        [ devfile.yaml file content ]
+      },
+      "supportedOdoFeatures": {
+        "dev": true,
+        "deploy": false,
+        "debug": true
+      }
+    }
+  },
+  [...]
 ]
 ```
 

docs/website/docs/command-reference/registry.md

@@ -18,10 +18,9 @@ These flags let you filter the listed Devfile stacks:
 when adding the registry to the preferences with `odo preference add registry <name> <url>`)
 * `--filter <term>` to list the Devfile for which the term is found in the devfile name or description
 
-By default, the name, registry and description 
-of the Devfile stacks are displayed on a table.
+By default, the name, registry, description and versions of the Devfile stacks are displayed on a table.
 
-This flag lets you change the content of the output:
+The flags below let you change the content of the output:
 
 * `--details` to display details about the Devfile stacks
 * `-o json` to output the information in a JSON format
@@ -50,18 +49,18 @@ odo registry
 
 ```console
 $ odo registry
- NAME                          REGISTRY                DESCRIPTION                                 
- dotnet50                      Staging                 Stack with .NET 5.0                         
- dotnet50                      DefaultDevfileRegistry  Stack with .NET 5.0                         
- dotnet60                      Staging                 Stack with .NET 6.0                         
- dotnet60                      DefaultDevfileRegistry  Stack with .NET 6.0                         
- dotnetcore31                  Staging                 Stack with .NET Core 3.1                    
- dotnetcore31                  DefaultDevfileRegistry  Stack with .NET Core 3.1                    
- go                            Staging                 Stack with the latest Go version            
- go                            DefaultDevfileRegistry  Stack with the latest Go version            
- java-maven                    Staging                 Upstream Maven and OpenJDK 11               
- java-maven                    DefaultDevfileRegistry  Upstream Maven and OpenJDK 11               
-[...]
+ NAME                          REGISTRY                DESCRIPTION                                  VERSIONS
+ dotnet50                      Staging                 Stack with .NET 5.0                          1.0.3
+ dotnet50                      DefaultDevfileRegistry  Stack with .NET 5.0                          1.0.3
+ dotnet60                      Staging                 Stack with .NET 6.0                          1.0.2
+ dotnet60                      DefaultDevfileRegistry  Stack with .NET 6.0                          1.0.2
+ dotnetcore31                  Staging                 Stack with .NET Core 3.1                     1.0.3
+ dotnetcore31                  DefaultDevfileRegistry  Stack with .NET Core 3.1                     1.0.3
+ go                            Staging                 Go is an open source programming languag...  1.0.2, 2.0.0
+ go                            DefaultDevfileRegistry  Go is an open source programming languag...  1.0.2, 2.0.0
+ java-maven                    Staging                 Upstream Maven and OpenJDK 11                1.2.0
+ java-maven                    DefaultDevfileRegistry  Upstream Maven and OpenJDK 11                1.2.0
+ [...]
 ```
 </details>
 
@@ -77,13 +76,13 @@ odo registry --devfile-registry <registry>
 
 ```console
 $ odo registry --devfile-registry Staging
- NAME                          REGISTRY                DESCRIPTION                                 
- dotnet50                      Staging                 Stack with .NET 5.0                         
- dotnet60                      Staging                 Stack with .NET 6.0                         
- dotnetcore31                  Staging                 Stack with .NET Core 3.1                    
- go                            Staging                 Stack with the latest Go version            
- java-maven                    Staging                 Upstream Maven and OpenJDK 11               
-[...]
+ NAME                          REGISTRY  DESCRIPTION                                  VERSIONS
+ dotnet50                      Staging   Stack with .NET 5.0                          1.0.3
+ dotnet60                      Staging   Stack with .NET 6.0                          1.0.2
+ dotnetcore31                  Staging   Stack with .NET Core 3.1                     1.0.3
+ go                            Staging   Go is an open source programming languag...  1.0.2, 2.0.0
+ java-maven                    Staging   Upstream Maven and OpenJDK 11                1.2.0
+ [...]
 ```
 </details>
 
@@ -98,15 +97,15 @@ odo registry --filter <keyword>
 
 ```console
 $ odo registry --filter Maven
- NAME                       REGISTRY                DESCRIPTION                                 
- java-maven                 Staging                 Upstream Maven and OpenJDK 11               
- java-maven                 DefaultDevfileRegistry  Upstream Maven and OpenJDK 11               
- java-openliberty           Staging                 Java application Maven-built stack using... 
- java-openliberty           DefaultDevfileRegistry  Java application Maven-built stack using... 
- java-websphereliberty      Staging                 Java application Maven-built stack using... 
- java-websphereliberty      DefaultDevfileRegistry  Java application Maven-built stack using... 
- java-wildfly-bootable-jar  Staging                 Java stack with WildFly in bootable Jar ... 
- java-wildfly-bootable-jar  DefaultDevfileRegistry  Java stack with WildFly in bootable Jar ... 
+ NAME                       REGISTRY                DESCRIPTION                                  VERSIONS
+ java-maven                 Staging                 Upstream Maven and OpenJDK 11                1.2.0
+ java-maven                 DefaultDevfileRegistry  Upstream Maven and OpenJDK 11                1.2.0
+ java-openliberty           Staging                 Java application Maven-built stack using...  0.9.0
+ java-openliberty           DefaultDevfileRegistry  Java application Maven-built stack using...  0.9.0
+ java-websphereliberty      Staging                 Java application Maven-built stack using...  0.9.0
+ java-websphereliberty      DefaultDevfileRegistry  Java application Maven-built stack using...  0.9.0
+ java-wildfly-bootable-jar  Staging                 Java stack with WildFly in bootable Jar ...  1.1.0
+ java-wildfly-bootable-jar  DefaultDevfileRegistry  Java stack with WildFly in bootable Jar ...  1.1.0
 ```
 </details>
 
@@ -125,17 +124,20 @@ Name: java-maven
 Display Name: Maven Java
 Registry: Staging
 Registry URL: https://registry.stage.devfile.io
-Version: 1.1.0
+Version: 1.2.0
 Description: Upstream Maven and OpenJDK 11 
 Tags: Java, Maven
-Project Type: maven
-Language: java
+Project Type: Maven
+Language: Java
 Starter Projects:
   - springbootproject
 Supported odo Features:
   - Dev: Y
   - Deploy: N
   - Debug: Y
+Versions:
+  - 1.2.0
+
 ```
 </details>
 

docs/website/docs/user-guides/quickstart/quickstart.md

@@ -18,30 +18,31 @@ A full list of example applications can be viewed with the `odo registry` comman
 
 ```shell
 $ odo registry
- NAME                          REGISTRY                DESCRIPTION                                 
- dotnet50                      DefaultDevfileRegistry  Stack with .NET 5.0                         
- dotnet60                      DefaultDevfileRegistry  Stack with .NET 6.0                         
- dotnetcore31                  DefaultDevfileRegistry  Stack with .NET Core 3.1                    
- go                            DefaultDevfileRegistry  Go is an open source programming languag... 
- java-maven                    DefaultDevfileRegistry  Upstream Maven and OpenJDK 11               
- java-openliberty              DefaultDevfileRegistry  Java application Maven-built stack using... 
- java-openliberty-gradle       DefaultDevfileRegistry  Java application Gradle-built stack usin... 
- java-quarkus                  DefaultDevfileRegistry  Quarkus with Java                           
- java-springboot               DefaultDevfileRegistry  Spring Boot® using Java                     
- java-vertx                    DefaultDevfileRegistry  Upstream Vert.x using Java                  
- java-websphereliberty         DefaultDevfileRegistry  Java application Maven-built stack using... 
- java-websphereliberty-gradle  DefaultDevfileRegistry  Java application Gradle-built stack usin... 
- java-wildfly                  DefaultDevfileRegistry  Upstream WildFly                            
- java-wildfly-bootable-jar     DefaultDevfileRegistry  Java stack with WildFly in bootable Jar ... 
- nodejs                        DefaultDevfileRegistry  Stack with Node.js 16                       
- nodejs-angular                DefaultDevfileRegistry  Angular is a development platform, built... 
- nodejs-nextjs                 DefaultDevfileRegistry  Next.js gives you the best developer exp... 
- nodejs-nuxtjs                 DefaultDevfileRegistry  Nuxt is the backbone of your Vue.js proj... 
- nodejs-react                  DefaultDevfileRegistry  React is a free and open-source front-en... 
- nodejs-svelte                 DefaultDevfileRegistry  Svelte is a radical new approach to buil... 
- nodejs-vue                    DefaultDevfileRegistry  Vue is a JavaScript framework for buildi... 
- php-laravel                   DefaultDevfileRegistry  Laravel is an open-source PHP framework,... 
- python                        DefaultDevfileRegistry  Python is an interpreted, object-oriente... 
- python-django                 DefaultDevfileRegistry  Django is a high-level Python web framew...
+ NAME                          REGISTRY                DESCRIPTION                                  VERSIONS
+ dotnet50                      DefaultDevfileRegistry  Stack with .NET 5.0                          1.0.3
+ dotnet60                      DefaultDevfileRegistry  Stack with .NET 6.0                          1.0.2
+ dotnetcore31                  DefaultDevfileRegistry  Stack with .NET Core 3.1                     1.0.3
+ go                            DefaultDevfileRegistry  Go is an open source programming languag...  1.0.2, 2.0.0
+ java-maven                    DefaultDevfileRegistry  Upstream Maven and OpenJDK 11                1.2.0
+ java-openliberty              DefaultDevfileRegistry  Java application Maven-built stack using...  0.9.0
+ java-openliberty-gradle       DefaultDevfileRegistry  Java application Gradle-built stack usin...  0.4.0
+ java-quarkus                  DefaultDevfileRegistry  Quarkus with Java                            1.3.0
+ java-springboot               DefaultDevfileRegistry  Spring Boot using Java                       1.2.0, 2.0.0
+ java-vertx                    DefaultDevfileRegistry  Upstream Vert.x using Java                   1.2.0
+ java-websphereliberty         DefaultDevfileRegistry  Java application Maven-built stack using...  0.9.0
+ java-websphereliberty-gradle  DefaultDevfileRegistry  Java application Gradle-built stack usin...  0.4.0
+ java-wildfly                  DefaultDevfileRegistry  Upstream WildFly                             1.1.0
+ java-wildfly-bootable-jar     DefaultDevfileRegistry  Java stack with WildFly in bootable Jar ...  1.1.0
+ nodejs                        DefaultDevfileRegistry  Stack with Node.js 16                        2.1.1
+ nodejs-angular                DefaultDevfileRegistry  Angular is a development platform, built...  2.0.2
+ nodejs-nextjs                 DefaultDevfileRegistry  Next.js gives you the best developer exp...  1.0.3
+ nodejs-nuxtjs                 DefaultDevfileRegistry  Nuxt is the backbone of your Vue.js proj...  1.0.3
+ nodejs-react                  DefaultDevfileRegistry  React is a free and open-source front-en...  2.0.2
+ nodejs-svelte                 DefaultDevfileRegistry  Svelte is a radical new approach to buil...  1.0.3
+ nodejs-vue                    DefaultDevfileRegistry  Vue is a JavaScript framework for buildi...  1.0.2
+ php-laravel                   DefaultDevfileRegistry  Laravel is an open-source PHP framework,...  1.0.1
+ python                        DefaultDevfileRegistry  Python is an interpreted, object-oriente...  2.1.0, 3.0.0
+ python-django                 DefaultDevfileRegistry  Django is a high-level Python web framew...  2.1.0
+
 ```
 </details>

pkg/api/registry.go

@@ -11,14 +11,29 @@ type Registry struct {
 
 // DevfileStack is the main struct for devfile stack
 type DevfileStack struct {
-	Name            string       `json:"name"`
-	DisplayName     string       `json:"displayName"`
-	Description     string       `json:"description"`
-	Registry        Registry     `json:"registry"`
-	Language        string       `json:"language"`
-	Tags            []string     `json:"tags"`
-	ProjectType     string       `json:"projectType"`
-	Version         string       `json:"version"`
-	StarterProjects []string     `json:"starterProjects"`
-	DevfileData     *DevfileData `json:"devfileData,omitempty"`
+	Name        string   `json:"name"`
+	DisplayName string   `json:"displayName"`
+	Description string   `json:"description"`
+	Registry    Registry `json:"registry"`
+	Language    string   `json:"language"`
+	Tags        []string `json:"tags"`
+	ProjectType string   `json:"projectType"`
+
+	// DefaultVersion is the default version. Marshalled as "version" for backward compatibility.
+	// Deprecated. Use Versions instead.
+	DefaultVersion string                `json:"version"`
+	Versions       []DevfileStackVersion `json:"versions,omitempty"`
+
+	// DefaultStarterProjects is the list of starter projects for the default stack.
+	// Marshalled as "starterProjects" for backward compatibility.
+	// Deprecated. Use Versions.StarterProjects instead.
+	DefaultStarterProjects []string     `json:"starterProjects"`
+	DevfileData            *DevfileData `json:"devfileData,omitempty"`
+}
+
+type DevfileStackVersion struct {
+	Version         string   `json:"version,omitempty"`
+	IsDefault       bool     `json:"isDefault"`
+	SchemaVersion   string   `json:"schemaVersion,omitempty"`
+	StarterProjects []string `json:"starterProjects"`
 }