rename Step 4a; normalize files/links in READMEs

Change-Id: Ieead4cbe61321627f1df6f17d6193f91d00dc6f4

Author: wescpy

README.md

@@ -43,7 +43,7 @@ We suggest considering where you want to end up eventually, playing with each mi
 
 Each major migration step has its own codelab & corresponding overview video. The step numbers correspond to their own folders, and generally each have folders for Python 2 & 3 ports. Some have an alternative or secondary succeeding migration&emdash;these end with "a", i.e., "Step 2a".
 
-1. Migrate from `webapp2` to Flask
+1. Migrate from `webapp2` to [Flask](https://flask.palletsprojects.com/)
     - Stongly recommended if you have a web UI
     - You can use another web framework as long as it supports routing
 1. Migrate from App Engine NDB to Cloud NDB
@@ -58,7 +58,7 @@ Each major migration step has its own codelab & corresponding overview video. Th
     - Can migrate to [Cloud Firestore](http://cloud.google.com/firestore) after this step (see Step 3a below)
         - Infrequent/uncommon as it is "expensive" (requires new project & you give up some performance)
         - It's for those who **must have** Firestore's (new) Firebase features
-1. Migrate from App Engine to Cloud Run (using Cloud Datastore)
+1. Migrate from App Engine to Cloud Run
     - Migrate your app to a container with Docker
     - Alternative container migration with Buildpacks (see Step "4a" below)
 
@@ -68,30 +68,37 @@ The table below summarizes each migration step and which options are available f
 
 Python 2 | Next | Python 3 | Description
 --- | --- | --- | ---
-`step0-webapp2-gaendb-py2` | ⇓ | _N/A_ | Original GAE sample on GAE `ndb` & `webapp2`
-`step1-flask-gaendb-py2` | ⇓ | _N/A_ | Migrate to Flask ("gaendb" _N/A_ for Python 3)
-`step2-flask-cloudndb-py2` | ⇓ or ⇒ or ⤓ª | `step2-flask-cloudndb-py3` | Migrate to Cloud NDB
-`step3-flask-datastore-py2` | ⇓ or ⇒ or ⤓+º | `step3-flask-datastore-py3` | Migrate to Cloud Datastore
-`step4-flask-cloudrun-py2` | ⇒ | `step4-flask-cloudrun-py3` | Migrate to Cloud Run (with Docker)
+[`step0-webapp2-gaendb-py2`](/step0-webapp2-gaendb-py2) | ⇓ | _N/A_ | Original GAE sample on GAE `ndb` & `webapp2`
+[`step1-flask-gaendb-py2`](/step1-flask-gaendb-py2) | ⇓ | _N/A_ | Migrate to Flask ("gaendb" _N/A_ for Python 3)
+[`step2-flask-cloudndb-py2`](/step2-flask-cloudndb-py2) | ⇓ or ⇒ or ⤓ª | [`step2-flask-cloudndb-py3`](/step2-flask-cloudndb-py3) | Migrate to Cloud NDB
+[`step3-flask-datastore-py2`](/step3-flask-datastore-py2) | ⇓ or ⇒ or ⤓+º | [`step3-flask-datastore-py3`]('step3-flask-datastore-py3) | Migrate to Cloud Datastore
+[ª`step4-cloudndb-cloudrun-py2`](/step4-cloudndb-cloudrun-py2) | ⇒ | [`step4-cloudds-cloudrun-py3`](/step4-cloudds-cloudrun-py3) | Migrate to Cloud Run (with Docker)
 
-### Alternatives
+* We recommend users complete what we consider the minimum migration (Steps 1 & 2).
+* If you a Python 2 App Engine app you want to modernize by containerizing, you can jump over Step 3 straight to Step 4 and stay there forever if desired.
+* Step 3's migration to Cloud Datastore is most useful if you have other apps using Cloud Datastore; you can make your codebase consistent by migrating from Cloud NDB to Cloud Datastore so all your Datastore access is consistent, possibly lowering your maintenance costs.
+* Migrating to Step 4 is only useful if you wish to containerize your app and run it serverlessly with Cloud Run. The Python 2 app uses Cloud NDB while the Python 3 equivalent uses Cloud Datastore.
 
-We recommend users complete what we consider the minimum migration (Steps 1 & 2). If there's no further interest in upgrading Datastore access nor migrating to Python 3, users can containerize their Python 2 apps for Cloud Run immediately (see Step 2a below). Why would you consider this? If you want to keep your app mostly as-is with minimal code changes otherwise (prefer no additional migrations) and want to containerize the app to make it more portable. This is Step 2a (and only Python 2 as expected).
+There are several alternatives to consider to the main steps above: 1) migrating to Cloud Firestore for those who desire to take advantage of the next-generation of Cloud Datastore that has features from the Firebase real-time database, and 2) an alternative to building containers using [Cloud Buildpacks](https://github.com/GoogleCloudPlatform/buildpacks) instead of Docker.
 
-Cloud Firestore is the next generation of Cloud Datastore, inheriting features from the Firebase real-time database. However, use of Cloud Datastore and Cloud Firestore are mutually-exclusive, meaning applications (Google Cloud projects) can only use one, and once data has been entered, it cannot switch to the other, so migrating to Firestore requires you to "host" your application on a completely different project. It is only for users where those new Firebase features are a **must-have**. This migration's tutorial is Step 3a.
+### Alternatives
 
-There are two ways to deploy containerized apps to Cloud Run, traditionally with Docker, or with the more recent [Cloud Buildpacks](https://github.com/GoogleCloudPlatform/buildpacks) (no Docker knowledge needed). Both Step 4 tutorials use Docker while Step 4a represents the alternative using Cloud Buildpacks. (Step 4a is only available in Python 3.)
+Cloud Firestore is the next generation of Cloud Datastore, inheriting features from the Firebase real-time database. However, use of Cloud Datastore and Cloud Firestore are mutually-exclusive, meaning applications (Google Cloud projects) can only use one, and once data has been entered, it cannot switch to the other, so migrating to Firestore requires you to "host" your application on a completely different project. It is only for users where those new Firebase features are a **must-have**. This migration's tutorial is Step 3a. There are two ways to deploy containerized apps to Cloud Run: Docker or Buildpacks. Those who don't want to learn Docker or don't want to be dependent on a single company like Docker would employ Buildpacks as an option. Step 4a represents the alternative to the Docker Step 4 tutorial by using Cloud Buildpacks. Both these alternatives are only available in Python 3.
 
 Python 2 | Next | Python 3 | Description
 --- | --- | --- | ---
-ª`step2a-flask-cloudndb-cloudrun-py2` | _N/A_ | _N/A_ | Migrate (Python 2, Flask, Cloud NDB app) to Cloud Run (with Docker)
-_N/A_ | _N/A_ | º`step3a-flask-firestore-py3` | Migrate to Cloud Firestore (uncommon; see above)
-_N/A_ | _N/A_ | +`step4a-flask-cloudrun-bldpks-py3` | Migrate to Cloud Run (with Cloud Buildpacks)
+_N/A_ | _N/A_ | º[`step3a-flask-firestore-py3`](/step3a-flask-firestore-py3) | Migrate to Cloud Firestore (uncommon; see above)
+_N/A_ | _N/A_ | +[`step4a-cloudrun-bldpks-py3`](/step4a-cloudrun-bldpks-py3) | Migrate to Cloud Run (with Cloud Buildpacks)
 
 ### Canonical code samples
 
 Links to a more complete, canonical sample app will be provided if available. Example: the [GAE NDB to Cloud NDB migration sample](https://github.com/GoogleCloudPlatform/python-docs-samples/tree/master/appengine/standard/migration/ndb/overview) featured in the App Engine [migration documentation](https://cloud.google.com/appengine/docs/standard/python/migrate-to-python3).
 
+## Next
+
+- [**Step 0:**](/step0-webapp2-gaendb-py2) Take a look at the original Python 2.7 App Engine NDB Datastore `webapp2` app source code.
+- [**Step 1:**](/step1-flask-gaendb-py2) Take the first tutorial and migrate away from `webapp2` to Flask.
+
 ## References
 
 - App Engine Migration

step1-flask-gaendb-py2/README.md

@@ -204,4 +204,4 @@ AFTER:
 
 ## Next
 
-In the next step, we will migrate from App Engine NDB to Google Cloud NDB, a key step because after you complete *that*, you can either stop there or be presented with a variety of options to choose from.
+[**Step 2:**](/step2-flask-cloudndb-py2) The next tutorial involves migrating from App Engine NDB to Google Cloud NDB, a key step because after you switch to the Cloud library, many options become available to you.

step2-flask-cloudndb-py2/README.md

@@ -158,9 +158,8 @@ def fetch_visits(limit):
 
 ## Next
 
-From here, you have some flexibility as to your next move. You can...
+From here, there's flexibility as to your next move. Choose any of these options:
 
-- Continue to use NDB but migrate your app to a container executing serverlessly on Cloud Run (see `step2a-flask-cloudndb-py2-cloudrun`)
-- Port your app to Python 3 (see `step2-flask-cloudndb-py3`)
-- Combine both of the above steps (migrate to Python 3 *and* Cloud Run; no example provided but extrapolate from above)
-- Further modernize Datastore access from Cloud NDB to the (official) Cloud Datastore library (how users *outside of* App Engine access Cloud Datastore) (see `step3-flask-datastore-py2`)
+- [**Step 2:**](/step2-flask-cloudndb-py3) Port your app to Python 3 to get you on the next generation App Engine runtime as Python 2 has reached its end-of-life.
+- [**Step 4:**](/step4-cloudndb-cloudrun-py2) Continue to use NDB but migrate your app to a container executing serverlessly on Cloud Run.
+- [**Step 3:**](/step3-flask-datastore-py2) Further modernize Datastore access from Cloud NDB to the (official) Cloud Datastore library (how users *outside of* App Engine access Cloud Datastore).

step2-flask-cloudndb-py3/README.md

@@ -35,5 +35,5 @@ handlers:
 
 From here, your options are:
 
-1. Migrate to Cloud Run (no example provided, but see: `step2a-flask-cloudndb-py2-cloudrun`)
-1. Further modernize Datastore access to Cloud Datastore (see `step3-flask-datastore-py3` and the `README.md` in `step3-flask-datastore-py2`).
+- [**Step 4:**](/step4-cloudndb-cloudrun-py2) Continue to use NDB but migrate your app to a container executing serverlessly on Cloud Run; also see [its Python 3 Datastore equivalent](/step4-cloudds-cloudrun-py3)
+- [**Step 3:**](/step3-flask-datastore-py2) Further modernize Datastore access from Cloud NDB to the (official) Cloud Datastore library (how users *outside of* App Engine access Cloud Datastore); also see [its Python 3 Datastore equivalent](/step3-flask-datastore-py3)

step3-flask-datastore-py2/README.md

@@ -196,7 +196,6 @@ def fetch_visits(limit):
 
 From here, you have some several options... you can:
 
-1. Migrate your app to Cloud Run (no example provided, but see `step2a-flask-cloudndb-py2-cloudrun`)
-1. Port your app to Python 3 (see `step3-flask-datastore-py3`)
-1. Combine both of the above steps (migrate to Python 3 *and* Cloud Run; no example provided but extrapolate from above)
-1. Further modernize Datastore access from Cloud Datastore to Cloud Firestore, allowing you to take full advantage of native Firestore features (see `step4-flask-firestore-py2`)
+- [**Step 3:**](/step3-flask-datastore-py3) Port your app to Python 3 to get you on the next generation App Engine runtime as Python 2 has reached its end-of-life.
+- [**Step 4:**](/step4-cloudds-cloudrun-py3) Migrate your app to Cloud Run (only available in Python 3; the [Python 2 equivalent](/step4-cloudndb-cloudrun-py2) is based on Cloud NDB.
+- [**Step 3a:**](/step3a-flask-firestore-py3) Migrate to Cloud Firestore, allowing you to take full advantage of native Firestore features (only available in Python 3).

step3-flask-datastore-py3/README.md

@@ -36,5 +36,5 @@ handlers:
 
 From here, your options are:
 
-1. Migrate your app to Cloud Run (no example provided, but see `step2a-flask-cloudndb-py2-cloudrun`)
-1. Further modernize Datastore access to Cloud Firestore, allowing you to take full advantage of native Firestore features (see `step4-flask-firestore-py3` and the `README.md` in `step4-flask-firestore-py2`).
+- [**Step 4:**](/step4-cloudds-cloudrun-py3) Migrate your app to Cloud Run (only available in Python 3; the [Python 2 equivalent](/step4-cloudndb-cloudrun-py2) is based on Cloud NDB.
+- [**Step 3a:**](/step3a-flask-firestore-py3) Migrate to Cloud Firestore, allowing you to take full advantage of native Firestore features (only available in Python 3).

step3a-flask-firestore-py3/README.md

@@ -215,8 +215,8 @@ def fetch_visits(limit):
 
 ## Next
 
-From here, you have some flexibility as to your next move. You can...
+From here, there really is only one (optional) migration to make, and that is to containerize your app. The other thing you can do is fully explore the capabilities of Cloud Firestore. Your options:
 
-1. Migrate your app to Cloud Run (`step4-flask-cloudrun-py2`).
-1. Port your app to Python 3 (see `step4a-flask-firestore-py3`)
-1. Combine both of the above steps (migrate to Python 3 *and* Cloud Run; no example provided but extrapolate from above)
+1. Explore other [Cloud Firestore](https://cloud.google.com/firestore) features.
+1. Step 4: No sample available but can adapt the Cloud Run migrations (see `step4-cloudndb-cloudrun-py2` [Python 2 Cloud NDB app] and `step4-cloudds-cloudrun-py3` [Python 3 Cloud Datastore app]) for Firestore.
+- [**Step 4:**](/step4-cloudds-cloudrun-py3) Migrate your app to Cloud Run (only available in Python 3 & Cloud Datastore; the [Python 2 equivalent](/step4-cloudndb-cloudrun-py2) is based on Cloud NDB; a Firestore port is easiest to extrapolate from the Python 3 Datastore app.

step4-cloudds-cloudrun-py3/README.md

@@ -21,7 +21,7 @@ App Engine existed before the concept of containers. Since Docker's launch, cont
 
 There are two options for users when migrating to a container, and it hinges upon what generation runtime your app is on as well as your [Docker](http://docker.com/) experience. Those on a newer runtime can use [Cloud Buildpacks](https://github.com/GoogleCloudPlatform/buildpacks) to containerize apps so they can be deployed to Cloud Run or other Google Cloud container platforms ([GCE](https://cloud.google.com/compute), [GKE](https://cloud.google.com/kubernetes-engine), [Anthos](http://cloud.google.com/anthos), etc.).
 
-See Step 4a (see `step4a-flask-datastore-py3-cloudrun`) if interested in using Buildpacks over Docker. However, if you're on a first generation runtime or prefer to use Docker, you're in the right place.
+See Step 4a (see `step4a-cloudrun-bldpks-py3`) if interested in using Buildpacks over Docker. However, if you're on a first generation runtime or prefer to use Docker, you're in the right place.
 
 ---
 
@@ -76,6 +76,6 @@ Doublecheck there are no files/folders named, `app.yaml`, `appengine_config.py`,
 
 ## Next
 
-Congratulations... your app is fully modernized now, concluding this tutorial. From here, there is only one more things you can investigate:
+Congratulations... your app is fully modernized now, concluding this tutorial. From here, there is only one more thing you can investigate:
 
-1. If you're seeking an alternative to containerizing your app *without* Docker, consider the alternative Step 4a which is identical to the sample app in *this* tutorial except it uses [Cloud Buildpacks](https://github.com/GoogleCloudPlatform/buildpacks) instead of Docker.
+- [**Step 4a:**](/step4a-cloudrun-bldpks-py3) An alternative to app in *this* tutorial, containerizing your app with [Cloud Buildpacks](https://github.com/GoogleCloudPlatform/buildpacks) instead of Docker.

step4-cloudndb-cloudrun-py2/README.md

@@ -9,7 +9,7 @@ The next (but still optional) step of migrating from App Engine to an explicit c
 - Helps move even further away from vendor lock-in, dependency on Google Cloud
 - Gives users the ability to more easily migrate their apps to VMs or Kubernetes, or move out of the cloud and run on-premise.
 
-This migration is slightly different from its Python 3 twin (the "other" Step 4) in that we're using Cloud NDB for this 2.x version but Cloud Datastore for the 3.x version. If you're ready for containerization, this tutorial show you how to migrate Python 2 App Engine apps using Cloud NDB to Cloud Run.
+This migration is slightly different from its Python 3 twin (the "other" Step 4) in that we're using Cloud NDB for this 2.x version but Cloud Datastore for the 3.x version. If you're ready for containerization, this tutorial show you how to migrate Python 2 App Engine apps using Cloud NDB to Cloud Run. If you want to modernize your app but want to stick with Python 2 forever, this is one way to do so.
 
 The steps include replacing the configuration files and specifying how your app should start. Since you won't have App Engine's web server, you'll need to specify your own server or bundle one into your container. For testing and staging, it's easy to just run Flask's development server from Python, but developers can opt for something more powerful for production such as the [Cloud Run Quickstart sample](https://cloud.google.com/run/docs/quickstarts/build-and-deploy) which uses `gunicorn`.
 
@@ -21,7 +21,7 @@ App Engine existed before the concept of containers. Since Docker's launch, cont
 
 There are two options for users when migrating to a container, and it hinges upon what generation runtime your app is on as well as your [Docker](http://docker.com/) experience. Those on a newer runtime can use [Cloud Buildpacks](https://github.com/GoogleCloudPlatform/buildpacks) to containerize apps so they can be deployed to Cloud Run or other Google Cloud container platforms ([GCE](https://cloud.google.com/compute), [GKE](https://cloud.google.com/kubernetes-engine), [Anthos](http://cloud.google.com/anthos), etc.).
 
-See Step 4a (see `step4a-flask-datastore-py3-cloudrun`) if interested in using Buildpacks over Docker. However, if you're on a first generation runtime or prefer to use Docker, you're in the right place.
+See Step 4a (see `step4a-cloudrun-bldpks-py3`) if interested in using Buildpacks over Docker. However, if you're on a first generation runtime or prefer to use Docker, you're in the right place.
 
 ---
 
@@ -78,5 +78,6 @@ Doublecheck there are no files/folders named, `app.yaml`, `appengine_config.py`,
 
 Congratulations... your app is fully modernized now, concluding this tutorial. From here, there are only a few more things you can investigate:
 
-1. Port your app to Python 3 (no example provided, but take a look at the "other" Step 4 which is an identical example except it is already Python 3 and uses Cloud Datastore instead of Cloud NDB.
-1. If you're seeking an alternative to containerizing your app *without* Docker, consider the alternative Step 4a which is identical to the Python 3 Step 4 except it uses [Cloud Buildpacks](https://github.com/GoogleCloudPlatform/buildpacks) instead of Docker.
+- [**Step 3:**](/step3-flask-datastore-py2) If you have non-App Engine apps using Cloud Datastore and want to make your codebase consistent, add the possibility of code reuse and reducing maintenance costs, migrate from Cloud NDB to Cloud Datastore. Backtrack and use Step 3 to inspire you if so. Cloud Datastore can be used with Cloud Run too.
+- [**Step 4:**](/step4-cloudndb-cloudrun-py2) Port your app to Python 3 (no example provided, but take a look at the "other" Step 4 which is an identical example except it is already Python 3 and uses Cloud Datastore instead of Cloud NDB.
+- [**Step 4a:**](/step4a-cloudrun-bldpks-py3) An alternative to app in *this* tutorial, containerizing your app with [Cloud Buildpacks](https://github.com/GoogleCloudPlatform/buildpacks) instead of Docker.