From a3cd1a31197794df0e70712b4a1f289d1db7ae0c Mon Sep 17 00:00:00 2001 From: Alex Dicianu Date: Mon, 19 Oct 2020 13:03:35 +0300 Subject: [PATCH 1/2] [CORE-2143] update readme for GA --- README.md | 56 ++++++++++++++++++++++++++++++++++++++++++++++++++----- 1 file changed, 51 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index e9815ef5..e25c8c98 100644 --- a/README.md +++ b/README.md @@ -1,9 +1,55 @@ -# 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-config/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-config + +Pantheon ships the `upstream-config/composer.json` file with the line +`"name": "pantheon-upstreams/upstream-config"`. 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-config` 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-config/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-config/composer.json` by running + `composer install` or `composer update` in the `upstream-config` directory. Just take care not to rely on + ["root-only" properties of composer.json](https://getcomposer.org/doc/04-schema.md). From 6e8641bb0099fed1ffd9edebe61356ec7f3a983b Mon Sep 17 00:00:00 2001 From: AlexD Date: Wed, 4 Nov 2020 14:06:36 +0200 Subject: [PATCH 2/2] more updates --- README.md | 135 ++++++++++++++++++++++++++++++++++++++++++++++++++---- 1 file changed, 127 insertions(+), 8 deletions(-) diff --git a/README.md b/README.md index e25c8c98..ea58ee10 100644 --- a/README.md +++ b/README.md @@ -8,7 +8,7 @@ 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-config/composer.json` should be regarded as owned by the upstream maintainer. It is included by the + * 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. @@ -28,16 +28,16 @@ Fork this repository on GitHub, and use the new repository as your starting poin 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-config +#### Edit the vendor name used in the upstream-configuration -Pantheon ships the `upstream-config/composer.json` file with the line -`"name": "pantheon-upstreams/upstream-config"`. You should change `pantheon-upstreams` to a name +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-config` directory to easily edit the upstream composer.json. +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 @@ -47,9 +47,128 @@ 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-config/composer.json`, always increment the `version` number listed in that file. + 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-config/composer.json` by running - `composer install` or `composer update` in the `upstream-config` directory. Just take care not to rely on + 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`.