Merge pull request #35 from navendu-pottekkat/update-documentation/na…

…vendu-pottekkat

Update documentation

README.md

@@ -1,120 +1,96 @@
-<p style="text-align:center;" align="center"><a href="https://layer5.io/meshery"><img align="center" style="margin-bottom:20px;" src="https://raw.githubusercontent.com/layer5io/meshery/master/.github/assets/images/meshery/meshery-logo-tag-light-text-side.png"  width="70%" /></a><br /><br /></p>
+<p style="text-align:center;" align="center"><a href="https://docs.meshery.io/guides/smi-conformance#running-smi-conformance-tests-in-cicd-pipelines"><img align="center" style="margin-bottom:20px;" src="./.github/readme/images/SMI%20Conformance%20with%20Meshery.jpeg" /></a><br /><br /></p>
 
 <p align="center">
-<a href="https://hub.docker.com/r/layer5/meshery" alt="Docker pulls">
-<img src="https://img.shields.io/docker/pulls/layer5/meshery.svg" /></a>
-<a href="https://goreportcard.com/report/github.com/layer5io/meshery" alt="Go Report Card">
-<img src="https://goreportcard.com/badge/github.com/layer5io/meshery" /></a>
-<a href="https://github.com/layer5io/meshery/actions" alt="Build Status">
-<img src="https://github.com/layer5io/meshery/workflows/Meshery/badge.svg" /></a>
-<a href="https://bestpractices.coreinfrastructure.org/projects/3564" alt="CLI Best Practices">
-<img src="https://bestpractices.coreinfrastructure.org/projects/3564/badge" /></a>
-<a href="https://github.com/layer5io/meshery" alt="Website">
-<img src="https://img.shields.io/website/https/layer5.io/meshery.svg" /></a>
-<a href="https://github.com/issues?utf8=✓&q=is%3Aopen+is%3Aissue+archived%3Afalse+org%3Alayer5io+label%3A%22help+wanted%22+" alt="GitHub issues by-label">
-<img src="https://img.shields.io/github/issues/layer5io/meshery/help%20wanted.svg" /></a>
+<a href="https://github.com/layer5io/meshery-smi-conformance-action/releases">
+<img alt="GitHub release (latest by date)" src="https://img.shields.io/github/v/release/layer5io/meshery-smi-conformance-action"></a>
+<a href="https://github.com/layer5io/meshery-smi-conformance-action/issues">
+<img alt="GitHub issues" src="https://img.shields.io/github/issues/layer5io/meshery-smi-conformance-action"> </a>
+<a href="https://github.com/layer5io/meshery-smi-conformance-action/blob/master/LICENSE" alt="LICENSE">
+<img src="https://img.shields.io/github/license/layer5io/meshery.svg" /></a>
 <a href="http://slack.layer5.io" alt="Join Slack">
 <img src="https://img.shields.io/badge/[email protected]?logo=slack"></a>
 <a href="https://twitter.com/intent/follow?screen_name=mesheryio" alt="Twitter Follow">
 <img src="https://img.shields.io/twitter/follow/layer5.svg?label=Follow+Layer5&style=social" /></a>
-<a href="https://github.com/layer5io/meshery" alt="LICENSE">
-<img src="https://img.shields.io/github/license/layer5io/meshery.svg" /></a>
 </p>
 
-[![smi-conformance](https://github.com/layer5io/meshery-smi-conformance-action/actions/workflows/smi-conformace.yml/badge.svg)](https://github.com/layer5io/meshery-smi-conformance-action/actions/workflows/smi-conformace.yml)
-
-<h5><p align="center"><i>If you’re using Meshery or if you like the project, please <a href="https://github.com/layer5io/meshery/stargazers">★</a> this repository to show your support! 🤩</i></p></h5>
-
-[Meshery](https://meshery.io) is the multi-service mesh management plane offering lifecycle, configuration, and performance management of service meshes and their workloads.
+# Meshery - SMI Conformance GitHub Action
 
-# Meshery GitHub Action for Service Mesh Interface Conformance
+GitHub Action to run [SMI Conformance](https://docs.meshery.io/functionality/service-mesh-interface) tests on CI/CD pipelines.
 
-GitHub Action for `mesheryctl mesh validate` for SMI conformance - https://meshery.io/service-mesh-interface
+Meshery is SMI's official tool for validating conformance. Learn more at [smi-spec.io](https://smi-spec.io/blog/validating-smi-conformance-with-meshery/).
 
-<img src="/.github/readme/images/smi-conformance.png" width="110px" align="left" style="margin-right: 10px;" />
+## Learn More
 
-**Learn More**
+- [Meshery and Service Mesh Interface](https://docs.meshery.io/functionality/service-mesh-interface)
+- [Guide: Running SMI Conformance Tests](https://docs.meshery.io/guides/smi-conformance)
+- [Conformance Test Details](https://layer5.io/projects/service-mesh-interface-conformance)
 - [SMI Conformance Dashboard](https://meshery.io/service-mesh-interface) (stand-alone)
 - [SMI Conformance Dashboard](https://layer5.io/service-mesh-landscape#smi) (service mesh landscape)
 - [Design Specification](https://docs.google.com/document/d/1HL8Sk7NSLLj-9PRqoHYVIGyU6fZxUQFotrxbmfFtjwc/edit#)
-- [Conformance Test Details](https://layer5.io/projects/service-mesh-interface-conformance)
+- [Supported Service Meshes](https://docs.meshery.io/service-meshes)
 
 ## Usage
 
-* **For initial releases, this action works the best with minikube clusters.**
-* We recommend using the [manusa/actions-setup-minikube](https://github.com/manusa/actions-setup-minikube) action.
-* We also recommend using the [ubuntu-latest](https://github.com/actions/virtual-environments#available-environments) environment.
+See [action.yml](action.yml)
 
-### Inputs
-```yaml
-  # this token is used to auth with meshery provider and persist conformance results
-  provider_token:
-    description: "Provider token to use. NOTE: value of the 'token' key in auth.json"
-    required: true
-
-  # the name of the service mesh to run tests on. Must be in compliance with the Service Mesh Performance specification.
-  # see: https://github.com/service-mesh-performance/service-mesh-performance/blob/1de8c93d8cba4ba8c1120fe09b7bf6ce0aa48c83/protos/service_mesh.proto#L15-L28
-  service_mesh:
-    # used for provisioning appropriate meshery-adatper
-    description: "SMP compatible name for service mesh to use. e.g: open_service_mesh, istio etc"
-    required: true
-
-  # to identify if you want to run the tests on a cluster having the service
-  # mesh pre-installed
-  mesh_deployed:
-    description: "A boolean. Set to true if you want to do tests on a custom deployment of the service mesh and not only on the latest release"
-  required: true
-```
+By default, this action brings its own Kubernetes cluster(minikube), deploys the latest release of the service mesh specified and runs conformance tests (see [Running on latest release](#running-on-latest-release)).
 
-### Example Configurations
+You can however bring your own clusters with a specific version of a service mesh installed and Meshery would automatically detect your environment and run the conformance test accordingly (see [Running on specific version](#running-on-specific-version)).
+
+See [Running SMI Conformance Tests in CI/CD Pipelines](https://docs.meshery.io/guides/smi-conformance#running-smi-conformance-tests-in-cicd-pipelines) for detailed instructions on setting up Meshery and authenticating the GitHub action.
+
+### Sample Configurations
+
+#### Running on latest release
+
+Meshery would handle setting up the environment, deploying the service mesh and running the conformance tests.
 
-#### Running SMI Conformance Tests on latest release of a Service Mesh
 ```yaml
-name: SMI Conformance Validation using Meshery
+name: SMI Conformance with Meshery
 on:
   push:
     tags:
       - 'v*'
 
 jobs:
-  do_conformance:
-    name: Conformance Validation
+  smi-conformance:
+    name: SMI Conformance
     runs-on: ubuntu-latest
     steps:
 
-      # This action takes care of installing a cluster, installing the latest
-      # release of a service mesh and running SMI Conformance Tests on it
       - name: SMI conformance tests
         uses: layer5io/mesheryctl-smi-conformance-action@master
         with:
-          provider_token: ${{ secrets.PROVIDER_TOKEN }}
+          provider_token: ${{ secrets.MESHERY_PROVIDER_TOKEN }}
           service_mesh: open_service_mesh
           mesh_deployed: false
 ```
 
-#### Running SMI Conformance Tests on any version of a service mesh
+#### Running on specific version 
+(bring your own cluster)
+
+The environment with the service mesh installed provided by the user and Meshery runs the conformance tests.
+
 ```yaml
-name: SMI Conformance Validation using Meshery
+name: SMI Conformance with Meshery
 on:
   push:
     branches:
       - 'master'
 
 jobs:
-  do_conformance:
-    name: SMI Conformance on every commit to master
+  smi-conformance:
+    name: SMI Conformance tests on master
     runs-on: ubuntu-latest
     steps:
 
-      # deploy k8s
-      - name: Deploy k8s
+      - name: Deploy k8s-minikube
         uses: manusa/[email protected]
         with:
           minikube version: 'v1.21.0'
           kubernetes version: 'v1.20.7'
           driver: docker
 
-      # Install the wanted version of your service mesh
       - name: Install OSM
         run: |
            curl -LO https://github.com/openservicemesh/osm/releases/download/v0.9.1/osm-v0.9.1-linux-amd64.tar.gz
@@ -124,16 +100,19 @@ jobs:
            PATH="$PATH:$HOME/osm/bin/"
            osm-bin install --osm-namespace default
 
-      # perform SMI conformance validation on the mesh installed in the cluster
       - name: SMI conformance tests
         uses: layer5io/mesheryctl-smi-conformance-action@master
         with:
-          provider_token: ${{ secrets.PROVIDER_TOKEN }}
+          provider_token: ${{ secrets.MESHERY_PROVIDER_TOKEN }}
           service_mesh: open_service_mesh
           mesh_deployed: true
 ```
 
+## Reporting Conformance
+
+Service mesh projects can report their SMI Conformance results automatically and update it on the [SMI Conformance Dashboard](https://meshery.io/service-mesh-interface).
 
+See [Reporting Conformance](https://docs.meshery.io/functionality/service-mesh-interface#reporting-conformance) for details on how to setup reporting.
 
 ## Join the service mesh community!
 

action.yml

@@ -2,22 +2,21 @@ name: "Service Mesh Interface Conformance with Meshery"
 description: "Validate SMI specifications using Meshery"
 author: "Layer5"
 inputs:
-  # this token is used to auth with meshery provider and persist conformance results
+  # token to authenticate with Meshery
+  # see: https://docs.meshery.io/guides/smi-conformance#running-smi-conformance-tests-in-cicd-pipelines
   provider_token:
-    description: "Provider token to use. NOTE: value of the 'token' key in auth.json"
+    description: "Provider token to use. NOTE: value of the 'token' key in auth.json."
     required: true
 
-  # the name of the service mesh to deploy. Must be in compliance with
+  # name of the service mesh to deploy. Must be compliant with the Service Mesh Performance specification.
   # https://github.com/service-mesh-performance/service-mesh-performance/blob/1de8c93d8cba4ba8c1120fe09b7bf6ce0aa48c83/protos/service_mesh.proto#L15-L28
   service_mesh:
-    # used for provisioning appropriate meshery-adatper
-    description: "SMP compatible name for service mesh to use. e.g: open_service_mesh, istio etc"
+    description: "Service Mesh to use."
     required: true
 
-  # to identify if you want to run the tests on a cluster having the service 
-  # mesh pre-installed
+  # set to true if you are bringing your own cluster with a service mesh installed
   mesh_deployed:
-    description: "Set to true if you want to do tests on a custom deployment of the service mesh and not only on the latest release"
+    description: "Set to true for custom service mesh deployments other than the latest release."
     required: true
 
 runs: