diff --git a/README.md b/README.md index e9815ef5..ea58ee10 100644 --- a/README.md +++ b/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`.