Clean up docs and meta files (#1721)

* Clean up docs and meta files

* Fix absolute link in release-cluster README

* Fix absolute link for the logo in README

* Revert move of root README

* Fix Online Boutique typo

* Update README.md

Co-authored-by: Nim Jayawardena <nimjay@google.com>

* Update README.md

* Fix issues with README quickstart

* Fix issues with README quickstart

* Update README.md

Co-authored-by: Nim Jayawardena <nimjay@google.com>

---------

Co-authored-by: Nim Jayawardena <nimjay@google.com>

.github/release-cluster/README.md

@@ -2,7 +2,7 @@
 
 This directory contains extra deploy manifests for configuring Online Boutique solution on GKE for onlineboutique.dev.
 
-_Note: before moving forward, the OnlineBoutique apps should already be deployed [on the online-boutique-release GKE cluster](../../hack#10-deploy-releasekubernetes-manifestsyaml-to-our-online-boutique-release-gke-cluster)._
+_Note: before moving forward, the Online Boutique apps should already be deployed [on the online-boutique-release GKE cluster](/docs/releasing#10-deploy-releasekubernetes-manifestsyaml-to-our-online-boutique-release-gke-cluster)._
 
 ## Public static IP address
 

docs/cloudshell-tutorial.md

@@ -4,7 +4,7 @@ This tutorial shows you how to deploy **[Online Boutique](https://github.com/Goo
 
 You'll be able to run Online Boutique on:
 - a local **[minikube](https://minikube.sigs.k8s.io/docs/)** cluster, which comes built in to the Cloud Shell instance
-- a **[Google Kubernetes Engine](https://cloud.google.com/kubernetes-engine)** cluster using a new or existing [Google Cloud Platform project](https://cloud.google.com/resource-manager/docs/creating-managing-projects#creating_a_project)
+- a **[Google Kubernetes Engine](https://cloud.google.com/kubernetes-engine)** cluster using a new or existing [Google Cloud project](https://cloud.google.com/resource-manager/docs/creating-managing-projects#creating_a_project)
 
 Let's get started!
 
@@ -29,7 +29,7 @@ Once minikube has started, you're ready to move on to the next step.
 
 ### GKE instructions
 
-In order to create a GKE cluster, you'll need to **[create a Google Cloud Platform project](https://cloud.google.com/resource-manager/docs/creating-managing-projects#creating_a_project)** or use an existing project.
+In order to create a GKE cluster, you'll need to **[create a Google Cloud project](https://cloud.google.com/resource-manager/docs/creating-managing-projects#creating_a_project)** or use an existing project.
 
 1. Access the command palette by going to **View > Find Command**.
 
@@ -83,7 +83,7 @@ You can start, stop, and debug apps from the Debug view.
 
 ### Clean up
 
-If you've deployed your app to a GKE cluster in your Google Cloud Platform project, you'll want to delete the cluster to avoid incurring charges.
+If you've deployed your app to a GKE cluster in your Google Cloud project, you'll want to delete the cluster to avoid incurring charges.
 
 1. Navigate to the <walkthrough-editor-spotlight spotlightId="activity-bar-cloud-k8s">Cloud Code - Kubernetes view</walkthrough-editor-spotlight> in the Activity bar.
 

docs/development-guide.md

@@ -1,13 +1,13 @@
 # Development Guide 
 
-This doc explains how to build and run the OnlineBoutique source code locally using the `skaffold` command-line tool.  
+This doc explains how to build and run the Online Boutique source code locally using the `skaffold` command-line tool.  
 
 ## Prerequisites 
 
 - [Docker for Desktop](https://www.docker.com/products/docker-desktop).
 - kubectl (can be installed via `gcloud components install kubectl`)
 - [skaffold **2.0.2+**](https://skaffold.dev/docs/install/) (latest version recommended), a tool that builds and deploys Docker images in bulk. 
-- A Google Cloud Project with Google Container Registry enabled. 
+- A Google Cloud project with Google Container Registry enabled. 
 - Enable GCP APIs for Cloud Monitoring, Tracing, Profiler:
 ```
 gcloud services enable monitoring.googleapis.com \
@@ -19,7 +19,7 @@ gcloud services enable monitoring.googleapis.com \
 
 ## Option 1: Google Kubernetes Engine (GKE)
 
-> 💡 Recommended if you're using Google Cloud Platform and want to try it on
+> 💡 Recommended if you're using Google Cloud and want to try it on
 > a realistic cluster. **Note**: If your cluster has Workload Identity enabled, 
 > [see these instructions](https://cloud.google.com/kubernetes-engine/docs/how-to/workload-identity#enable)
 

docs/releasing/README.md

@@ -0,0 +1,65 @@
+# Releasing Online Boutique
+
+This document walks through the process of creating a new release of Online Boutique.
+
+## Creating a new release
+
+1. Decide on the next release version number using [semantic versioning](https://semver.org/), based on the [commits since the previous release](https://github.com/GoogleCloudPlatform/microservices-demo/commits/main).
+
+2. Open a new terminal.
+
+3. Make sure you have `gsed` installed. If not, `brew install gnu-sed`.
+
+4. Set the following environment variables:
+
+   - `TAG` - This is the new version (e.g., `v0.3.5`).
+   - `REPO_PREFIX` - This is the Docker repository.
+
+   **Example:**
+
+   ```
+   export TAG=v0.3.5
+   export REPO_PREFIX=gcr.io/google-samples/microservices-demo
+   ```
+
+5. Run `./docs/releasing/make-release.sh`.
+
+   - Make sure you run `./docs/releasing/make-release.sh` from this project's root directory — **not** from inside the `docs/releasing/` directory.
+   - This script:
+     1. uses `make-docker-images.sh` to build and push a Docker image for each microservice to the previously specified repository.
+     1. uses `make-release-artifacts.sh` to regenerates (and update the image $TAGS) YAML file at `./release/kubernetes-manifests.yaml` and `./kustomize/base/`.
+     1. runs `git tag` and pushes a new branch (e.g., `release/v0.3.5`) with the changes to `./release/kubernetes-manifests.yaml`.
+
+6. Make sure the new Docker images were created and pushed.
+
+   - Go through [our Container Registry repository](https://pantheon.corp.google.com/gcr/images/google-samples/global/microservices-demo?project=google-samples).
+   - Make sure a Docker image was created for each microservice (with the new version tag).
+
+7. [Draft a new release on GitHub](https://github.com/GoogleCloudPlatform/microservices-demo/releases).
+
+   - Summarize the [commits since the previous release](https://github.com/GoogleCloudPlatform/microservices-demo/commits/main).
+   - See previous releases for inspiration on release notes.
+
+8. Create a new pull-request.
+
+   - When you ran `make-release.sh`, it created a new branch (e.g., `release/v0.3.5`).
+   - Include the new release draft in the pull-request description for reviewers to see.
+
+9. Once your pull-request is approved, merge it.
+
+10. Connect to our [online-boutique-release GKE cluster](https://pantheon.corp.google.com/kubernetes/clusters/details/us-central1-c/online-boutique-release/details?project=online-boutique-ci).
+
+   ```
+   gcloud container clusters get-credentials online-boutique-release \
+     --zone us-central1-c --project online-boutique-ci
+   ```
+
+11. Deploy `release/kubernetes-manifests.yaml` to our [online-boutique-release GKE cluster](https://pantheon.corp.google.com/kubernetes/clusters/details/us-central1-c/online-boutique-release/details?project=online-boutique-ci).
+
+   ```
+   kubectl apply -f ./release/kubernetes-manifests.yaml
+   ```
+
+12. Make sure [onlineboutique.dev](https://onlineboutique.dev) works.
+
+13. [Publish your draft release on GitHub](https://github.com/GoogleCloudPlatform/microservices-demo/releases).

hack/make-docker-images.sh → docs/releasing/make-docker-images.sh

@@ -17,7 +17,8 @@
 # Builds and pushes docker image for each demo microservice.
 
 set -euo pipefail
-SCRIPTDIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )"
+SCRIPT_DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )"
+REPO_ROOT=$SCRIPT_DIR/../..
 
 log() { echo "$1" >&2; }
 
@@ -50,6 +51,6 @@ while IFS= read -d $'\0' -r dir; do
             docker push "${image}-native-grpc-probes"
         fi
     )
-done < <(find "${SCRIPTDIR}/../src" -mindepth 1 -maxdepth 1 -type d -print0)
+done < <(find "${REPO_ROOT}/src" -mindepth 1 -maxdepth 1 -type d -print0)
 
 log "Successfully built and pushed all images."

hack/make-helm-chart.sh → docs/releasing/make-helm-chart.sh

@@ -17,14 +17,15 @@
 # Packages and pushes Online Boutique's Helm chart in public Artifact Registry.
 
 set -euo pipefail
-SCRIPTDIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )"
+SCRIPT_DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )"
+REPO_ROOT=$SCRIPT_DIR/../..
 
 log() { echo "$1" >&2; }
 
 TAG="${TAG:?TAG env variable must be specified}"
 HELM_CHART_REPO="us-docker.pkg.dev/online-boutique-ci/charts"
 
-cd helm-chart
+cd ${REPO_ROOT}/helm-chart
 gsed -i "s/^appVersion:.*/appVersion: \"${TAG}\"/" Chart.yaml
 gsed -i "s/^version:.*/version: ${TAG:1}/" Chart.yaml
 helm package .

hack/make-release-artifacts.sh → docs/releasing/make-release-artifacts.sh

@@ -18,17 +18,18 @@
 # /release/...
 
 set -euo pipefail
-SCRIPTDIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )"
+SCRIPT_DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )"
+REPO_ROOT=$SCRIPT_DIR/../..
 [[ -n "${DEBUG:-}" ]] && set -x
 
 log() { echo "$1" >&2; }
 
 TAG="${TAG:?TAG env variable must be specified}"
 REPO_PREFIX="${REPO_PREFIX:?REPO_PREFIX env variable must be specified}"
-OUT_DIR="${OUT_DIR:-${SCRIPTDIR}/../release}"
+OUT_DIR="${OUT_DIR:-${REPO_ROOT}/release}"
 
 print_license_header() {
-    cat "${SCRIPTDIR}/license_header.txt"
+    cat "${SCRIPT_DIR}/license_header.txt"
     echo
 }
 
@@ -61,7 +62,7 @@ read_manifests_except_kustomization() {
 }
 
 mk_kubernetes_manifests() {
-    out_manifest="$(read_manifests_except_kustomization "${SCRIPTDIR}/../kubernetes-manifests")"
+    out_manifest="$(read_manifests_except_kustomization "${REPO_ROOT}/kubernetes-manifests")"
 
     # replace "image" repo, tag for each service
     for dir in ./src/*/
@@ -88,7 +89,7 @@ mk_istio_manifests() {
 
     # This just copies the yaml from the component (excluding kustomization.yaml)
     # since there is no easy way to render individual kustomize component resources
-    read_manifests_except_kustomization "${SCRIPTDIR}/../kustomize/components/service-mesh-istio/"
+    read_manifests_except_kustomization "${REPO_ROOT}/kustomize/components/service-mesh-istio/"
     echo '# [END servicemesh_release_istio_manifests_microservices_demo]'
 }
 

hack/make-release.sh → docs/releasing/make-release.sh

@@ -21,7 +21,8 @@
 # - 4. pushing the tag/commit to main.
 
 set -euo pipefail
-SCRIPTDIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )"
+SCRIPT_DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )"
+REPO_ROOT=$SCRIPT_DIR/../..
 [[ -n "${DEBUG:-}" ]] && set -x
 
 log() { echo "$1" >&2; }
@@ -45,19 +46,19 @@ git checkout main
 git pull
 
 # build and push images
-"${SCRIPTDIR}"/make-docker-images.sh
+"${SCRIPT_DIR}"/make-docker-images.sh
 
 # update yaml
-"${SCRIPTDIR}"/make-release-artifacts.sh
+"${SCRIPT_DIR}"/make-release-artifacts.sh
 
 # build and push images
-"${SCRIPTDIR}"/make-helm-chart.sh
+"${SCRIPT_DIR}"/make-helm-chart.sh
 
 # create git release / push to new branch
 git checkout -b "release/${TAG}"
-git add "${SCRIPTDIR}/../release/"
-git add "${SCRIPTDIR}/../kustomize/base/"
-git add "${SCRIPTDIR}/../helm-chart/"
+git add "${REPO_ROOT}/release/"
+git add "${REPO_ROOT}/kustomize/base/"
+git add "${REPO_ROOT}/helm-chart/"
 git commit --allow-empty -m "Release $TAG"
 log "Pushing k8s manifests to release/${TAG}..."
 git tag "$TAG"

kustomize/components/service-mesh-istio/README.md

@@ -198,7 +198,7 @@ INGRESS_HOST="$(kubectl get gateway istio-gateway \
 curl -v "http://$INGRESS_HOST"
 ```
 
-# Additional service mesh demos using OnlineBoutique 
+# Additional service mesh demos using Online Boutique 
 
 - [Canary deployment](https://github.com/GoogleCloudPlatform/istio-samples/tree/master/istio-canary-gke)
 - [Security (mTLS, JWT, Authorization)](https://github.com/GoogleCloudPlatform/istio-samples/tree/master/security-intro)

src/adservice/genproto.sh

@@ -18,6 +18,6 @@
 # protos are needed in adservice folder for compiling during Docker build.
 
 mkdir -p proto && \
-cp ../../pb/demo.proto src/main/proto
+cp ../../protos/demo.proto src/main/proto
 
 # [END gke_adservice_genproto]

src/checkoutservice/genproto.sh

@@ -17,7 +17,7 @@
 # [START gke_checkoutservice_genproto]
 
 PATH=$PATH:$GOPATH/bin
-protodir=../../pb
+protodir=../../protos
 
 protoc --go_out=plugins=grpc:genproto -I $protodir $protodir/demo.proto
 

src/currencyservice/genproto.sh

@@ -18,6 +18,6 @@
 
 # protos are loaded dynamically for node, simply copies over the proto.
 mkdir -p proto
-cp -r ../../pb/* ./proto
+cp -r ../../protos/* ./proto
 
 # [END gke_currencyservice_genproto]

src/emailservice/genproto.sh

@@ -16,6 +16,6 @@
 
 # [START gke_emailservice_genproto]
 
-python -m grpc_tools.protoc -I../../pb --python_out=. --grpc_python_out=. ../../pb/demo.proto
+python -m grpc_tools.protoc -I../../protos --python_out=. --grpc_python_out=. ../../protos/demo.proto
 
 # [END gke_emailservice_genproto]

src/frontend/genproto.sh

@@ -17,7 +17,7 @@
 # [START gke_frontend_genproto]
 
 PATH=$PATH:$GOPATH/bin
-protodir=../../pb
+protodir=../../protos
 
 protoc --go_out=plugins=grpc:genproto -I $protodir $protodir/demo.proto
 

src/paymentservice/genproto.sh

@@ -18,6 +18,6 @@
 
 # protos are loaded dynamically for node, simply copies over the proto.
 mkdir -p proto
-cp -r ../../pb/* ./proto
+cp -r ../../protos/* ./proto
 
 # [END gke_paymentservice_genproto]

src/productcatalogservice/genproto.sh

@@ -17,7 +17,7 @@
 # [START gke_productcatalogservice_genproto]
 
 PATH=$PATH:$GOPATH/bin
-protodir=../../pb
+protodir=../../protos
 
 protoc --go_out=plugins=grpc:genproto -I $protodir $protodir/demo.proto
 

src/recommendationservice/genproto.sh

@@ -21,6 +21,6 @@
 # requires gRPC tools:
 #   pip install -r requirements.txt
 
-python -m grpc_tools.protoc -I../../pb --python_out=. --grpc_python_out=. ../../pb/demo.proto
+python -m grpc_tools.protoc -I../../protos --python_out=. --grpc_python_out=. ../../protos/demo.proto
 
 # [END gke_recommendationservice_genproto]

src/shippingservice/genproto.sh

@@ -17,7 +17,7 @@
 # [START gke_shippingservice_genproto]
 
 PATH=$PATH:$GOPATH/bin
-protodir=../../pb
+protodir=../../protos
 
 protoc --go_out=plugins=grpc:genproto -I $protodir $protodir/demo.proto