README cleanup

Author: wescpy

mod15-blobstore/README.md

@@ -1,9 +1,9 @@
-# Module 15 - Add usage of App Engine `blobstore` to baseline sample app (Module 0)
+# Module 15 - Add usage of App Engine `blobstore` to `webapp2 ndb` sample app
 
-This repo folder is the corresponding code to the [Module 14 codelab](http://g.co/codelabs/pae-migrate-blobstore). The tutorial STARTs with the Python 2 code in the [Module 0 repo folder](/mod0-baseline) and leads developers through adding use of App Engine `blobstore`. Unlike other sample apps, this does not use the default Django templating system, but instead, uses Jinja2, which is supported in `webapp2_extras`.
+This repo folder is the corresponding code to the (forthcoming) Module 15 codelab. The tutorial STARTs with the Python 2 code in the [Module 0 repo folder](/mod0-baseline) and leads developers through adding use of App Engine `blobstore`. Unlike other sample apps, this does not use the default Django templating system, but instead, uses Jinja2, which is supported in `webapp2_extras`.
 
-Blobstore evolved into [Google Cloud Storage](https://cloud.google.com/storage), and all blobs/files created using the Blobstore API go into the default Cloud Storage bucket for your Cloud project, which is the project's ID, meaning it's your `appspot` domain name, e.g., for project `my-project`, your default bucket would be `my-project.appspot.com`. It is programmatically accessible via `google.appengine.api.app_identity.get_default_gcs_bucket_name()`.
+Blobstore evolved into [Google Cloud Storage](https://cloud.google.com/storage), and all blobs/files created using the Blobstore API go into the default Cloud Storage bucket for your project. It's named the same as the `appspot` domain name given to your app. For example, if your project is named `my-project`, your default bucket would be `my-project.appspot.com`. The default GCS bucket name is programmatically accessible via `google.appengine.api.app_identity.get_default_gcs_bucket_name()`.
 
-The primary application file [`main.py`](main.py) writes files directly to the default bucket. If you want to customize the GCS location where App Engine writes files, see the alternative [`main-gcs.py`](main-gcs.py) file. It uses `google.appengine.api.app_identity.get_default_gcs_bucket_name()` along with the `gs_bucket_name` parameter when calling `google.appengine.ext.blobstore.create_upload_url()`.
+The primary application file [`main.py`](main.py) writes files directly to the default bucket. If you want to customize the GCS location where App Engine writes files, see the alternative [`main-gcs.py`](main-gcs.py) file. In that file, the `gs_bucket_name` parameter is used when calling `google.appengine.ext.blobstore.create_upload_url()` to specify the bucket/location to write the file.
 
-Unlike some of the other migrations, Blobstore usage depends on the `webapp` and `webapp2`, so this migration must start at Module 0 rather than Module 1. One update however, is that this sample does use the [Jinja2 templating system](https://jinja.palletsprojects.com) rather than the default Django templates used in Module 0. It is supported in `webapp2` via the `webapp2_extras` package.
+Unlike some of the other migrations, Blobstore usage depends on `webapp` (where as the app uses the `webapp2` micro framework), so this migration must start at Module 0 rather than Module 1. One update however, is that this sample switches to the [Jinja2 templating system](https://jinja.palletsprojects.com) from the default Django template system used in Module 0. Jinja2 is supported as an App Engine [built-in library](https://cloud.google.com/appengine/docs/standard/python/tools/built-in-libraries-27) and accessed via the `webapp2_extras` package.

mod16-cloudstorage/README.md

@@ -1,5 +1,7 @@
 # Module 16 - Migrate from App Engine `blobstore` to Cloud Storage
 
+## Migrations
+
 This repo folder is the corresponding code to the [Module 16 codelab](http://g.co/codelabs/pae-migrate-blobstore). The tutorial STARTs with the Python 2 code in the [Module 15 repo folder](/mod15-blobstore) and leads developers through a set of migrations, culminating in the code in this folder. In addition to migrating to Cloud Storage, a few others are done to get from Modules 15 to 16... here is the complete list:
 
 1. Migrate from App Engine `webapp2` to Flask
@@ -8,7 +10,17 @@ This repo folder is the corresponding code to the [Module 16 codelab](http://g.c
 
 The reason why the web framework requires migration is because `blobstore` has dependencies on `webapp` and `webapp2`, so we could not start directly from a Flask app.
 
+## Python compatibility
+
 This app is fully Python 2-3 compatible. To do a Python 3 deployment of this app:
 
 1. Edit `app.yaml` by enabling/uncommenting the `runtime: python39` line
-1. Delete all other lines in `app.yaml`, save, and deploy with `gcloud app deploy`
+1. Delete all other lines in `app.yaml` and save
+1. Delete `lib` (if present) and `appengine_config.py` (neither used in Python 3)
+1. Deploy with `gcloud app deploy`
+
+## Backwards compatibility
+
+One catch with this migration is that `blobstore` has a dependency on `webapp`. By migrating to Cloud Storage, that dependency is not resolved because the app was also migrated from `webapp2` (and `webapp`) to Flask. In real life, there may not be an option to just discard all your data. The [`main.py`](main.py) in this folder is for the easy situation where you _can_, replacing `ndb.BlobKeyProperty` (for Blobstore files) with `ndb.StringProperty` (for Cloud Storage files) in the data model.
+
+For the rest of us, we may need [`main-migrate.py`](main-migrate.py), an alternative version of the application. The data model here maintains a `ndb.BlobKeyProperty` for backwards-compatibility and creates a 4th field for the Cloud Storage filename (`ndb.StringProperty`). Furthermore, an additional `etl_visits()` function is required to consolidate files created with Blobstore _and_ Cloud Storage without changing the HTML template.