Template Subfolder convention

README.md

@@ -185,7 +185,9 @@ https://github.com/hashicorp/go-getter library, including:
 In essence, a template is a directory or directory-like object containing a
 "spec file", named `spec.yaml`
 ([example](https://github.com/abcxyz/abc/blob/main/examples/templates/render/hello_jupiter/spec.yaml)),
-and other files such as source code and config files.
+and other files such as source code and config files. 
+
+The recommended convention is to have all files intended to be included placed in a subfolder named "contents". This way, non-template related files (GitHub workflows, metadata, template READMEs, etc.) can exist next to the spec.yaml.
 
 ### Model of operation
 
@@ -202,7 +204,7 @@ Template rendering has a few phases:
     ```yaml
     - action: 'include'
       params:
-        paths: ['main.go']
+        paths: ['contents/main.go']
     ```
   - The `append`, `string_replace`, `regex_replace`, `regex_name_lookup`, and
     `go_template` actions transform the files that are in the scratch directory
@@ -227,7 +229,7 @@ The spec file, named `spec.yaml` describes the template, including:
   user-provided input named `service_name`).
 
 The following is an example spec file. It has a single templated file,
-`main.go`, and during template rendering all instances of the word `world` are
+`contents/main.go`, and during template rendering all instances of the word `world` are
 replaced by a user-provided string. Thus "hello, world" is transformed into
 "hello, $whatever" in `main.go`.
 
@@ -245,7 +247,8 @@ steps:
   - desc: 'Include some files and directories'
     action: 'include'
     params:
-      paths: ['main.go']
+      paths: ['contents']
+      as: ['.']
   - desc: 'Replace "world" with user-provided input'
     action: 'string_replace'
     params:
@@ -342,15 +345,15 @@ Examples:
   ```yaml
   - action: 'include'
     params:
-      paths: ['main.go', '{{.user_requested_config}}/config.txt']
+      paths: ['contents/main.go', 'contents/{{.user_requested_config}}/config.txt']
   ```
 
 - Using `as` to relocate files:
 
   ```yaml
   - action: 'include'
     params:
-      paths: ['{{.dbname}}/db.go']
+      paths: ['contents/{{.dbname}}/db.go']
       as: ['db.go']
   ```
 
@@ -369,7 +372,7 @@ Examples:
   ```yaml
   - action: 'include'
     params:
-      paths: ['configs']
+      paths: ['contents/configs']
       skip: ['unwanted_subdir', 'unwanted_file.txt']
   ```
 
@@ -427,7 +430,7 @@ Example:
 ```yaml
 - action: 'append'
   params:
-    paths: ['foo.html', 'web/']
+    paths: ['foo.html', 'web']
     with: '</html>\n'
     skip_ensure_newline: false
 ```

t/data_migration_pipeline/README.md

@@ -1,67 +1,24 @@
 # Template: Data migration pipeline
-Simple Spanner data migration pipeline in Go, using Apache Beam to migrate from a MySQL CSV dump.
-To run this, please follow these steps:
-1. cd into an empty directory
+
+Template for a simple Spanner data migration pipeline in Go, using Apache Beam to migrate from a MySQL CSV dump. 
+
+How to render this template:
+
+1. [Install the abc binary](https://github.com/abcxyz/abc#installation).
+
+1. cd into an empty destination directory.
 
     ```shell
     $ mkdir ~/spanner_migration_project
     $ cd ~/spanner_migration_project
     ```
-1. Install the `abc` binary
-    ```shell
-    $ go install github.com/abcxyz/abc/cmd/abc@latest
-    $ abc --help
-    ```
-    This only works if you have go installed (https://go.dev/doc/install) and have the Go binary directory in your $PATH.
-1. Execute the template defined in the `t` directory.
-This will output a file named `main.go` in your working directory containing
-the template program.
-    ```shell
-    $ abc templates render github.com/abcxyz/abc.git//t/data_migration_pipeline
-    ```
-1. Start a local Spanner emulator. If the emulator is not installed already, you will be prompted to download and install the binary for the emulator.
-    ```shell
-    $ gcloud components update
-    $ gcloud emulators spanner start
-    ```
-1. Create a dedicated gcloud configuration that allows disable authentication and override the endpoint.
-Once configured, your gcloud commands will be sent to the emulator instead of the production service. No worries, you'll be able to switch back to your previous configurations at the end of this guide.
-    ```shell
-    $ gcloud config configurations create emulator
-    $ gcloud config set auth/disable_credentials true
-    $ gcloud config set project [your-project-id]
-    $ gcloud config set api_endpoint_overrides/spanner http://localhost:9020/
-    ```
-1. Create a test database to host your pipeline output.
-    ```shell
-    $ gcloud spanner instances create test-instance \
-   --config=emulator-config --description="Test Instance" --nodes=1
-    $ gcloud spanner databases create testdb --instance=test-instance --ddl='CREATE TABLE mytable (Id STRING(36)) PRIMARY KEY(Id)'
-    ```
-   - make sure the local Spanner emulator runs in a separated tab.
-
-7. Point your client libraries to the emulator.
-When pipeline starts, the client library automatically checks for SPANNER_EMULATOR_HOST and connects to the emulator if it is running.
-    ```shell
-    $ export SPANNER_EMULATOR_HOST=localhost:9010
-    ```
-1. Run the data migration pipeline in dry run mode. Verify metrics like total record count. 
-    ```shell
-    $ go run main.go -input-csv-path "test-data.csv" -spanner-database "projects/[your-project-id]/instances/test-instance/databases/testdb" -spanner-table "mytable" -dry-run=true
-    ```
-    - flag `-dry-run=true` is to active the dry run mode.
 
-1. Run the data migration pipeline in the real run and write into Spanner.
+1. Render via:
 
     ```shell
-    $ go run main.go -input-csv-path "test-data.csv" -spanner-database "projects/[your-project-id]/instances/test-instance/databases/testdb" -spanner-table "mytable"
+    $ abc templates render github.com/abcxyz/abc.git//t/data_migration_pipeline
     ```
 
-1. Verify the MySQL CSV dump has been successfully migrated to your Spanner database
-    ```shell
-    $ gcloud spanner databases execute-sql testdb --instance=test-instance --sql='SELECT * FROM mytable'
-    ```
-1. Switch back to your default gcloud configurations
-    ```shell
-    $ gcloud config configurations activate default
-    ```
+    This will output a file named `main.go` in your working directory containing the template program.
+
+1. Follow the steps in the rendered README.md to run the application.

t/data_migration_pipeline/contents/README.md

@@ -0,0 +1,50 @@
+# Data migration pipeline
+
+Simple Spanner data migration pipeline in Go, using Apache Beam to migrate from a MySQL CSV dump. 
+
+1. Start a local Spanner emulator. If the emulator is not installed already, you will be prompted to download and install the binary for the emulator.
+    ```shell
+    $ gcloud components update
+    $ gcloud emulators spanner start
+    ```
+1. Create a dedicated gcloud configuration that allows disable authentication and override the endpoint.
+Once configured, your gcloud commands will be sent to the emulator instead of the production service. No worries, you'll be able to switch back to your previous configurations at the end of this guide.
+    ```shell
+    $ gcloud config configurations create emulator
+    $ gcloud config set auth/disable_credentials true
+    $ gcloud config set project [your-project-id]
+    $ gcloud config set api_endpoint_overrides/spanner http://localhost:9020/
+    ```
+1. Create a test database to host your pipeline output.
+    ```shell
+    $ gcloud spanner instances create test-instance \
+   --config=emulator-config --description="Test Instance" --nodes=1
+    $ gcloud spanner databases create testdb --instance=test-instance --ddl='CREATE TABLE mytable (Id STRING(36)) PRIMARY KEY(Id)'
+    ```
+   - make sure the local Spanner emulator runs in a separated tab.
+
+7. Point your client libraries to the emulator.
+When pipeline starts, the client library automatically checks for SPANNER_EMULATOR_HOST and connects to the emulator if it is running.
+    ```shell
+    $ export SPANNER_EMULATOR_HOST=localhost:9010
+    ```
+1. Run the data migration pipeline in dry run mode. Verify metrics like total record count. 
+    ```shell
+    $ go run main.go -input-csv-path "test-data.csv" -spanner-database "projects/[your-project-id]/instances/test-instance/databases/testdb" -spanner-table "mytable" -dry-run=true
+    ```
+    - flag `-dry-run=true` is to active the dry run mode.
+
+1. Run the data migration pipeline in the real run and write into Spanner.
+
+    ```shell
+    $ go run main.go -input-csv-path "test-data.csv" -spanner-database "projects/[your-project-id]/instances/test-instance/databases/testdb" -spanner-table "mytable"
+    ```
+
+1. Verify the MySQL CSV dump has been successfully migrated to your Spanner database
+    ```shell
+    $ gcloud spanner databases execute-sql testdb --instance=test-instance --sql='SELECT * FROM mytable'
+    ```
+1. Switch back to your default gcloud configurations
+    ```shell
+    $ gcloud config configurations activate default
+    ```

t/data_migration_pipeline/spec.yaml

@@ -21,9 +21,10 @@ steps:
   - desc: 'Include some files and directories'
     action: 'include'
     params:
-      paths: ['.']
+      paths: ['contents']
+      as: ['.']
   - desc: 'Print user instructions'
     action: 'print'
     params:
       message:
-        'Please go to the main.go and replace the the data model (hint text: "Your data model goes here.") and the data processing logic (hint text: "Your data parsing logic goes here.")'
+        'Successfully rendered template. Please go to the rendered main.go and replace the the data model (hint text: "Your data model goes here.") and the data processing logic (hint text: "Your data parsing logic goes here.")'

t/react_template/README.md

@@ -2,85 +2,21 @@
 
 # Template: React Framework
 
-This template was bootstrapped with [Create React App](https://github.com/facebook/create-react-app). 
+Template for a simple React App, bootstrapped with [Create React App](https://github.com/facebook/create-react-app). 
 
-The react template enpower the front end development flow by adding automate Continuous Build (CB) and Continuous Testing (CT). GitHub Actions are leveraged to perform a series of pre-submit validations. 
+## Template Rendering Instructions
 
-A branch protection rule will be established to enforce checks on each pull request including
+1. [Install the abc binary](https://github.com/abcxyz/abc#installation).
 
-- Lint to provide static analysis (with ESlint)
-- Code format (with Prettier)
-- Build (with React-scripts)
-- Unit test and Component test
-- Integration test (with Cypress)
-
-
-## Set up instruction
-
-1. cd into an empty directory
+1. cd into an empty destination directory.
 
     ```shell
     $ mkdir ~/react_template
     $ cd ~/react_template
     ```
-1. Install the `abc` [instructions](https://github.com/abcxyz/abc#user-guide)
-
 
-
-1. Execute the template defined in the `t` directory.
-This will output a file named `main.go` in your working directory containing
-the transformed program.
+1. Render via:
 
     ```shell
     $ abc templates render github.com/abcxyz/abc.git//t/react_template
     ```
-
-## Available Scripts
-prerequisites: `node.js` and `npm`. If not, follow the download steps [here](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm).
-
-In the project directory, you can run:
-
-### `npm start`
-
-Runs the app in the development mode. Open [http://localhost:3000](http://localhost:3000) to view it in your browser.
-
-The page will reload when you make changes. You may also see any lint errors in the console.
-
-### `npm test`
-
-Launches the test runner in the interactive watch mode.
-See the section about [running tests](https://facebook.github.io/create-react-app/docs/running-tests) for more information.
-
-### `npm run lint`
-
-Apply static analysis and code format checks.
-
-### `npm run fix`
-
-Automatically fix the code problem with Eslint, Prettier and GTS.
-
-### `npm run build`
-
-Builds the app for production to the `build` folder. 
-
-It correctly bundles React in production mode and optimizes the build for the best performance.
-
-The build is minified and the filenames include the hashes. 
-
-Your app is ready to be deployed!
-
-See the section about [deployment](https://facebook.github.io/create-react-app/docs/deployment) for more information.
-
-## Cypress test
-
-Recommend [Cypress Chrome Recorder](https://chrome.google.com/webstore/detail/cypress-chrome-recorder/fellcphjglholofndfmmjmheedhomgin?hl=en), a Chrome extension. It allows exporting tests directly from the Recorder panel.
-
-### `npm run cy:open`
-
-Run cypress cmd to open the cypress launchpad in the browser of the same machine. The running machine should meet [Linux Prerequisites](https://docs.cypress.io/guides/getting-started/installing-cypress#Linux-Prerequisites). For example, if the running is in cloudtop environment, the launchpad should also open on the cloudtop. 
-
-Choose Electron as the target testing browser. Chrome won't work. 
-
-### `npm run cy:test`
-
-Run cypress tests locally. Keep the server running when testing. Make sure to run the test before submit any CL.

t/react_template/contents/README.md

@@ -0,0 +1,67 @@
+# React Framework
+
+This template was bootstrapped with [Create React App](https://github.com/facebook/create-react-app). 
+
+The react template enpower the front end development flow by adding automate Continuous Build (CB) and Continuous Testing (CT). GitHub Actions are leveraged to perform a series of pre-submit validations. 
+
+A branch protection rule will be established to enforce checks on each pull request including
+
+- Lint to provide static analysis (with ESlint)
+- Code format (with Prettier)
+- Build (with React-scripts)
+- Unit test and Component test
+- Integration test (with Cypress)
+
+## Available Scripts
+prerequisites: `node.js` and `npm`. If not, follow the download steps [here](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm).
+
+In the project directory, you can run:
+
+### `npm install`
+
+Downloads necessary packages to run the application.
+
+### `npm start`
+
+Runs the app in the development mode. Open [http://localhost:3000](http://localhost:3000) to view it in your browser.
+
+The page will reload when you make changes. You may also see any lint errors in the console.
+
+### `npm test`
+
+Launches the test runner in the interactive watch mode.
+See the section about [running tests](https://facebook.github.io/create-react-app/docs/running-tests) for more information.
+
+### `npm run lint`
+
+Apply static analysis and code format checks.
+
+### `npm run fix`
+
+Automatically fix the code problem with Eslint, Prettier and GTS.
+
+### `npm run build`
+
+Builds the app for production to the `build` folder. 
+
+It correctly bundles React in production mode and optimizes the build for the best performance.
+
+The build is minified and the filenames include the hashes. 
+
+Your app is ready to be deployed!
+
+See the section about [deployment](https://facebook.github.io/create-react-app/docs/deployment) for more information.
+
+## Cypress test
+
+Recommend [Cypress Chrome Recorder](https://chrome.google.com/webstore/detail/cypress-chrome-recorder/fellcphjglholofndfmmjmheedhomgin?hl=en), a Chrome extension. It allows exporting tests directly from the Recorder panel.
+
+### `npm run cy:open`
+
+Run cypress cmd to open the cypress launchpad in the browser of the same machine. The running machine should meet [Linux Prerequisites](https://docs.cypress.io/guides/getting-started/installing-cypress#Linux-Prerequisites). For example, if the running is in cloudtop environment, the launchpad should also open on the cloudtop. 
+
+Choose Electron as the target testing browser. Chrome won't work. 
+
+### `npm run cy:test`
+
+Run cypress tests locally. Keep the server running when testing. Make sure to run the test before submitting any pull request.