[CORE-2143] update readme for GA

README.md

@@ -1,9 +1,174 @@
-# Composer-enabled Upstream template
-## Experimental
+# Composer-enabled Upstream Drupal 8 template
 
 This is Pantheon's recommended starting point for forking new upstreams that work with the Platform's integrated
 Composer build process.
 
-Because it is under active development, you should not create permanent/production sites using this repository
-yet. We make no guarantees of backwards compatibility. Merging new updates from this repository may break existing
-sites.
+We've empowered Pantheon Upstreams to influence the Composer packages that are included in downstream sites
+by including two `composer.json` files in this repository:
+  * The root `/composer.json` should be regarded as owned by the downstream site. Upstream maintainers should avoid
+    editing it as much as possible so that the downstream site maintainer may adjust it without creating potential
+    for conflicts when merging upstream updates.
+  * The `upstream-configuration/composer.json` should be regarded as owned by the upstream maintainer. It is included by the
+    root `composer.json`, and it allows upstreams to add or remove packages on downstream sites. These changes will be
+    automatically incorporated into the downstream site whenever upstream updates are applied.
+
+The Composer build system that's integrated into the Pantheon Platform does not require you to use this method, but
+it is Pantheon's recommendation. Upstreams with more complex needs could choose other methods to separate
+the downstream `composer.json` from the upstream's, such as by using [wikimedia/composer-merge-plugin](https://github.com/wikimedia/composer-merge-plugin).
+
+While this repository is designed to be forked, it is possible to use it directly as an upstream and
+create sites from it.
+
+## Documentation for upstream maintainers
+
+### Create your fork
+
+Fork this repository on GitHub, and use the new repository as your starting point for custom upstreams.
+
+Once you've forked this repository, Pantheon's documentation can help you [connect your repository to
+Pantheon.](https://pantheon.io/docs/create-custom-upstream#connect-repository-to-pantheon)
+
+#### Edit the vendor name used in the upstream-configuration
+
+Pantheon ships the `upstream-configuration/composer.json` file with the line 
+`"name": "pantheon-upstreams/upstream-configuration"`. You should change `pantheon-upstreams` to a name
+more befitting your organization, and update the `require` section of the root `/composer.json`
+file to match it.
+
+#### Add and remove packages
+
+You can use `composer require` inside the `upstream-configuration` directory to easily edit the upstream composer.json.
+
+A note about themes: This template places a theme in the upstream composer.json. This choice best fits situations
+where the downstream sites will all use the same theme. If your upstream does not mean to lock downstream sites
+into a particular theme, you should remove themes from the upstream composer.json. Sites are unable to remove packages
+included by the upstream from those that are installed.
+
+### Maintain your fork
+
+When you make modifications to your upstream based on this repository, a few special considerations apply:
+  1. When editing `upstream-configuration/composer.json`, always increment the `version` number listed in that file.  
+     Depending on the contents of the root `/composer.json`, this is sometimes necessary for Composer to detect the
+     changes to your upstream configuration.
+  2. You can perform a quick sanity check of your changes to `upstream-configuration/composer.json` by running
+    `composer install` or `composer update` in the `upstream-configuration` directory. Just take care not to rely on
+    ["root-only" properties of composer.json](https://getcomposer.org/doc/04-schema.md).
+
+## Creating a site
+
+1. Fork the Pantheon-maintained repository into your own github account.
+
+2. [Add a new Custom Upstream](https://pantheon.io/docs/create-custom-upstream#create-and-host-the-repository-remotely) on the Pantheon dashboard.
+
+3. Create a new site from the upstream to confirm that it’s working.
+
+   - Do not customize the upstream yet.
+
+4. In the Dev environment, click **Visit Development Site** and follow the prompts to complete the CMS installation.
+
+5. [Clone the site locally](https://pantheon.io/docs/local-development#get-the-code) and run `composer install`.
+
+## Upstream and Site Structure
+
+The upstream has the following directory structure:
+
+```
+core/
+├─ .gitignore
+├─ composer.json
+└─ pantheon.upstream.yml
+├─ README.md
+└─ upstream-configuration/
+   └─ composer.json
+```
+
+- `.gitignore`: Prevents build artifacts generated by Composer from being committed to the upstream or site code repositories.
+- `composer.json`: The two different `composer.json` files allow customization of individual sites without inherent merge conflicts and enable one-click updates.
+  - Root-level: Site-level customizations.
+  - `upstream-configuration/composer.json`: Customizations for the upstream
+- `pantheon.upstream.yml`: The `build_step: true` directive in `pantheon.upstream.yml` enables the build step.
+
+When a site is created, Pantheon runs `composer install`, generates a `composer.lock` file and commits it back to the site’s code repository.
+
+Build artifacts are stored in a Git tag (`pantheon_build_artifacts_master`), not the main branch (`master` for Dev or a Multidev feature branch).
+
+## How to Add Dependencies to Your Upstream
+
+1. Start with the local clone of the upstream repository you created above.
+
+2. Change into the `upstream-configuration` directory:
+
+  ```
+  cd upstream-configuration
+  ```
+
+3. Run:
+
+  ```
+  composer require drupal/pkg-name --no-update
+  ```
+
+4. Confirm the current configuration version:
+
+  ```
+  composer config version
+  1.0.0
+  ```
+
+5. Increment the config version number. If you don't increment the version number, updated dependencies will be ignored. Replace `x.y.z` in this example with something like `1.0.1`:
+
+  ```
+  composer config version x.y.z
+  ```
+
+6. Commit and push.
+
+## Applying One-click Updates
+
+Navigate to **Code** in the Dev tab of the site's Dashboard. Click **Check Now**. If updates are available, click **Apply Updates**.
+
+## Add a Dependency to an Individual Site
+
+1. Clone the git repository from the Pantheon site's dashboard.
+
+2. Run `composer install`:
+
+  ```
+  composer install
+  ```
+
+3. Add a new dependency locally:
+
+  ```
+  composer require drupal/pkg-name
+  ```
+
+4. Commit `composer.json` and `composer.lock` and push.
+
+   - Pantheon will run Composer, generate build artifacts, and deploy it to your Dev or Multidev environment.
+
+## Troubleshooting / FAQ
+
+### What Composer commands does Pantheon run?
+
+- Check for and applying updates:
+
+  ```
+  composer --no-cache --no-interaction --no-progress --prefer-dist update
+  ```
+
+- On all builds except applying updates:
+
+  ```
+  composer --no-cache --no-interaction --no-progress --prefer-dist install
+  ```
+
+### How do I view Composer's changes?
+
+Use `git diff` to view changes, excluding composer.lock
+
+```
+git diff d94d1a1179 -- . ':(exclude)composer.lock'
+```
+
+Try [composer-lock-diff](https://github.com/davidrjonas/composer-lock-diff) to see what packages have changed after `composer update`.