Merge remote-tracking branch 'origin/master' into HEAD

Author: briandealwis

DEVELOPMENT.md

@@ -103,6 +103,58 @@ For more details behind the logic of config changes see [the Skaffold config man
 
 We build the API directly through gRPC, which gets translated into REST API through a reverse proxy gateway library. If you make changes to the [proto/skaffold.proto](https://github.com/GoogleContainerTools/skaffold/blob/master/proto/skaffold.proto) file you can run `./hack/generate-proto.sh` to generate the equivalent Go code. 
 
+## Adding actionable error messages to code.
+Skaffold has a built-in framework to provide actionable error messages for user to help bootstrap skaffold errors.
+
+Also, [v1.19.0](https://github.com/GoogleContainerTools/skaffold/releases/tag/v1.19.0) onwards, skaffold is collecting failure error codes to help the team get more insights into common failure scenarios.
+
+To take advantage of this framework, contributors can simply use the [`ErrDef`](https://github.com/GoogleContainerTools/skaffold/blob/master/pkg/skaffold/errors/err_def.go#L32) struct to throw meaningful actionable error messages and 
+improve user experience.
+
+e.g In this example [PR](https://github.com/GoogleContainerTools/skaffold/pull/5273), 
+1. The contributor created 3 distinct error codes in [skaffold.proto](https://github.com/GoogleContainerTools/skaffold/pull/5088/files#diff-3883fe4549a47ae73a7a3a0afc00896b197d5ba8570906ba423769cf5a93a26f)
+   ```
+    // Docker build error when listing containers.
+    INIT_DOCKER_NETWORK_LISTING_CONTAINERS = 122;
+    // Docker build error indicating an invalid container name (or id).
+    INIT_DOCKER_NETWORK_INVALID_CONTAINER_NAME = 123;
+    // Docker build error indicating the container referenced does not exists in the docker context used.
+    INIT_DOCKER_NETWORK_CONTAINER_DOES_NOT_EXIST = 124
+   ```
+   The `INIT` in this case stands for skaffold `INIT` phase which includes, parsing of skaffold config and creating a skaffold runner. 
+   The other valid phases are `BUILD`, `DEPLOY`, `STATUSCHECK`. Complete list [here](https://skaffold.dev/docs/references/api/grpc/#statuscode)
+2. Run `hack/generate_proto.sh`. These will generate go code and structs for the newly added proto fields.
+   ```shell script
+    git status
+	   modified:   docs/content/en/api/skaffold.swagger.json
+	   modified:   docs/content/en/docs/references/api/grpc.md
+	   modified:   proto/skaffold.pb.go
+	   modified:   proto/skaffold.proto
+   ```
+3. The contributor then used these error codes when creating an error in their [proposed code change](https://github.com/GoogleContainerTools/skaffold/pull/5088/files#diff-3fc5246574bf7367a232c6d682b22a4e22795d52eb1c81fe2c27ff052939d507R220).
+   They used the constructor `sErrors.NewError` in [pkg/skaffold/errors](https://github.com/GoogleContainerTools/skaffold/blob/54466ff6983e9fcf977d6e549119b4c1c4dc9e2b/pkg/skaffold/errors/err_def.go#L57) to inantiate an object of struct `ErrDef`. 
+   `ErrDef` implements the golang `error` interface.
+   ```
+    err :=  sErrors.NewError(fmt.Errorf(errMsg), 
+      proto.ActionableErr{
+	    Message: errMsg,
+	    ErrCode: proto.StatusCode_INIT_DOCKER_NETWORK_INVALID_CONTAINER_NAME,
+		  Suggestions: []*proto.Suggestion{
+	  	    {
+			  SuggestionCode: proto.SuggestionCode_FIX_DOCKER_NETWORK_CONTAINER_NAME,
+			  Action:         "Please fix the docker network container name and try again",
+		    },
+		  },
+	  }))
+   ```
+
+With above two changes, skaffold will now show a meaning full error message when this error condition is met. 
+```shell script
+skaffold dev 
+invalid skaffold config: container 'does-not-exits' not found, required by image 'skaffold-example' for docker network stack sharing.
+Please fix the docker network container name and try again.
+```
+
 ## Building skaffold
 
 To build with your local changes you have two options:

docs/config.toml

@@ -82,7 +82,7 @@ weight = 1
 copyright = "Skaffold Authors"
 privacy_policy = "https://policies.google.com/privacy"
 github_repo = "https://github.com/GoogleContainerTools/skaffold"
-skaffold_version = "skaffold/v2beta11"
+skaffold_version = "skaffold/v2beta12"
 
 # Google Custom Search Engine ID. Remove or comment out to disable search.
 # gcs_engine_id = "013756393218025596041:3nojel67sum"

docs/content/en/api/skaffold.swagger.json

@@ -19,46 +19,78 @@ Your use of this software is subject to the [Google Privacy Policy](https://poli
 
 {{% tabs %}}
 {{% tab "LINUX" %}}
-The latest **stable** binary can be found here:
+The latest **stable** binaries can be found here:
 
 https://storage.googleapis.com/skaffold/releases/latest/skaffold-linux-amd64
+https://storage.googleapis.com/skaffold/releases/latest/skaffold-linux-arm64
 
-Simply download it and add it to your `PATH`. Or, copy+paste this command in your terminal:
+Simply download the appropriate binary and add it to your `PATH`. Or, copy+paste one of the following commands in your terminal:
 
 ```bash
+# For Linux AMD64
 curl -Lo skaffold https://storage.googleapis.com/skaffold/releases/latest/skaffold-linux-amd64 && \
 sudo install skaffold /usr/local/bin/
 ```
 
+```bash
+# For Linux ARM64
+curl -Lo skaffold https://storage.googleapis.com/skaffold/releases/latest/skaffold-linux-arm && \
+sudo install skaffold /usr/local/bin/
+```
+
 We also release a **bleeding edge** build, built from the latest commit:
 
 https://storage.googleapis.com/skaffold/builds/latest/skaffold-linux-amd64
+https://storage.googleapis.com/skaffold/builds/latest/skaffold-linux-arm64
 
 ```bash
+# For Linux on AMD64
 curl -Lo skaffold https://storage.googleapis.com/skaffold/builds/latest/skaffold-linux-amd64 && \
 sudo install skaffold /usr/local/bin/
 ```
 
+```bash
+# For Linux on ARM64
+curl -Lo skaffold https://storage.googleapis.com/skaffold/builds/latest/skaffold-linux-arm64 && \
+sudo install skaffold /usr/local/bin/
+```
+
 {{% /tab %}}
 
 {{% tab "MACOS" %}}
 
-The latest **stable** binary can be found here:
+The latest **stable** binaries can be found here:
 
 https://storage.googleapis.com/skaffold/releases/latest/skaffold-darwin-amd64
+https://storage.googleapis.com/skaffold/releases/latest/skaffold-darwin-arm64
+
+Simply download the appropriate binary and add it to your `PATH`. Or, copy+paste one of the following commands in your terminal:
 
-Simply download it and add it to your `PATH`. Or, copy+paste this command in your terminal:
+```bash
+# For macOS on AMD64
+curl -Lo skaffold https://storage.googleapis.com/skaffold/releases/latest/skaffold-darwin-amd64 && \
+sudo install skaffold /usr/local/bin/
+```
 
 ```bash
+# For macOS on ARM64
 curl -Lo skaffold https://storage.googleapis.com/skaffold/releases/latest/skaffold-darwin-amd64 && \
 sudo install skaffold /usr/local/bin/
 ```
 
 We also release a **bleeding edge** build, built from the latest commit:
 
 https://storage.googleapis.com/skaffold/builds/latest/skaffold-darwin-amd64
+https://storage.googleapis.com/skaffold/builds/latest/skaffold-darwin-arm64
+
+```bash
+# For macOS on AMD64
+curl -Lo skaffold https://storage.googleapis.com/skaffold/builds/latest/skaffold-darwin-amd64 && \
+sudo install skaffold /usr/local/bin/
+```
 
 ```bash
+# For macOS on ARM64
 curl -Lo skaffold https://storage.googleapis.com/skaffold/builds/latest/skaffold-darwin-amd64 && \
 sudo install skaffold /usr/local/bin/
 ```

docs/content/en/docs/install/_index.md

@@ -845,12 +845,12 @@ Enum indicating deploy tools used
 <a name="proto.StatusCode"></a>
 
 ### StatusCode
-Enum for Status codes
+Enum for Status codes<br>
 These error codes are prepended by Phase Name e.g.
-BUILD, TEST, DEPLOY, STATUSCHECK, DEVINIT
-For Success Error codes, use range 200 to 250.
-For Unknown error codes, use range 500 to 600.
-For Cancelled Error code, use range 800 to 850.
+INIT, BUILD, TEST, DEPLOY, STATUSCHECK, DEVINIT<br>
+For Success Error codes, use range 200 to 250.<br>
+For Unknown error codes, use range 500 to 600.<br>
+For Cancelled Error code, use range 800 to 850.<br>
 
 | Name | Number | Description |
 | ---- |:------:| ----------- |

docs/content/en/docs/references/api/grpc.md

@@ -723,7 +723,7 @@ Options:
   -f, --filename='skaffold.yaml': Path or URL to the Skaffold config file
   -m, --module=[]: Filter Skaffold configs to only the provided named modules
       --overwrite=false: Overwrite original config with fixed config
-      --version='skaffold/v2beta11': Target schema version to upgrade to
+      --version='skaffold/v2beta12': Target schema version to upgrade to
 
 Usage:
   skaffold fix [options]