From 8db66a6e715fd9ebe9b98b764cb093c497ef6554 Mon Sep 17 00:00:00 2001 From: Alex Skrypnyk Date: Tue, 14 May 2024 20:10:47 +1000 Subject: [PATCH] [10.x] Updated readme. --- README.md | 99 +++++++++++++++++++++++++++++-------------------------- 1 file changed, 52 insertions(+), 47 deletions(-) diff --git a/README.md b/README.md index 864fa9d12..962e82219 100644 --- a/README.md +++ b/README.md @@ -1,93 +1,98 @@ # Composer template for Drupal projects [![CI](https://github.com/drupal-composer/drupal-project/actions/workflows/ci.yml/badge.svg?branch=10.x)](https://github.com/drupal-composer/drupal-project/actions/workflows/ci.yml) +![LICENSE](https://img.shields.io/github/license/drupal-composer/drupal-project) This project template provides a starter kit for managing your site dependencies with [Composer](https://getcomposer.org/). -## Usage +> [!IMPORTANT] +> [Drupal 11 branch](https://github.com/drupal-composer/drupal-project/tree/11.x) is available! + +## What does the template do? + +* Drupal will be installed in the `web` directory. +* Generated composer autoloader `vendor/autoload.php` is used instead of + `web/vendor/autoload.php` provided by Drupal core. +* Modules (packages of type `drupal-module`) will be placed in `web/modules/contrib` directory. +* Themes (packages of type `drupal-theme`) will be placed in `web/themes/contrib` directory. +* Profiles (packages of type `drupal-profile`) will be placed in `web/profiles/contrib` directory. +* Creates default writable versions of `settings.php` and `services.yml`. +* Creates `web/sites/default/files` directory. +* Drush is installed for use as `vendor/bin/drush`. +* Provides an [example](.env.example) of the `.env` file. -First you need to [install Composer](https://getcomposer.org/doc/00-intro.md#installation-linux-unix-osx). +## Installing -> Note: The instructions below refer to the [global Composer installation](https://getcomposer.org/doc/00-intro.md#globally). +> [!NOTE] +> The instructions below refer to the [global Composer installation](https://getcomposer.org/doc/00-intro.md#globally). You might need to replace `composer` with `php composer.phar` (or similar) for your setup. -After that you can create the project: +Create your project: -``` +```bash composer create-project drupal-composer/drupal-project:10.x-dev some-dir --no-interaction ``` -With `composer require ...` you can download new dependencies to your -installation. - -``` -cd some-dir -composer require drupal/devel -``` - The `composer create-project` command passes ownership of all files to the project that is created. You should create a new Git repository, and commit all files not excluded by the `.gitignore` file. -## What does the template do? +## Usage -When installing the given `composer.json` some tasks are taken care of: +### Adding new dependencies -* Drupal will be installed in the `web`-directory. -* Autoloader is implemented to use the generated composer autoloader in `vendor/autoload.php`, - instead of the one provided by Drupal (`web/vendor/autoload.php`). -* Modules (packages of type `drupal-module`) will be placed in `web/modules/contrib/` -* Theme (packages of type `drupal-theme`) will be placed in `web/themes/contrib/` -* Profiles (packages of type `drupal-profile`) will be placed in `web/profiles/contrib/` -* Creates default writable versions of `settings.php` and `services.yml`. -* Creates `web/sites/default/files`-directory. -* Latest version of drush is installed locally for use at `vendor/bin/drush`. -* Latest version of DrupalConsole is installed locally for use at `vendor/bin/drupal`. -* Creates environment variables based on your .env file. See [.env.example](.env.example). +Use `composer require` to include and download dependencies for your project. -## Updating Drupal Core +```bash +cd some-dir +composer require drupal/devel +``` + +### Updating Drupal Core This project will attempt to keep all of your Drupal Core files up-to-date; the project [drupal/core-composer-scaffold](https://github.com/drupal/core-composer-scaffold) -is used to ensure that your scaffold files are updated every time drupal/core is -updated. If you customize any of the "scaffolding" files (commonly `.htaccess`), +is used to ensure that your scaffold files are updated every time `drupal/core` +is updated. + +If you customize any of the "scaffolding" files (commonly `.htaccess`), you may need to merge conflicts if any of your modified files are updated in a new release of Drupal core. -Follow the steps below to update your core files. +Follow the steps below to update your Drupal core files. 1. Run `composer update "drupal/core-*" --with-dependencies` to update Drupal Core and its dependencies. 2. Run `git diff` to determine if any of the scaffolding files have changed. Review the files for any changes and restore any customizations to `.htaccess` or `robots.txt`. -1. Commit everything all together in a single commit, so `web` will remain in +3. Commit everything all together in a single commit, so `web` will remain in sync with the `core` when checking out branches or running `git bisect`. -1. In the event that there are non-trivial conflicts in step 2, you may wish +4. In the event that there are non-trivial conflicts in step 2, you may wish to perform these steps on a branch, and use `git merge` to combine the updated core files with your customized files. This facilitates the use of a [three-way merge tool such as kdiff3](http://www.gitshah.com/2010/12/how-to-setup-kdiff-as-diff-tool-for-git.html). This setup is not necessary if your changes are simple; keeping all of your modifications at the beginning or end of the file is a good strategy to keep merges easy. -## FAQ +## FAQs ### Should I commit the contrib modules I download? Composer recommends **no**. They provide [argumentation against but also -workrounds if a project decides to do it anyway](https://getcomposer.org/doc/faqs/should-i-commit-the-dependencies-in-my-vendor-directory.md). +workarounds if a project decides to do it anyway](https://getcomposer.org/doc/faqs/should-i-commit-the-dependencies-in-my-vendor-directory.md). ### Should I commit the scaffolding files? The [Drupal Composer Scaffold](https://github.com/drupal/core-composer-scaffold) -plugin can download the scaffold files (like index.php, update.php, …) to the -web/ directory of your project. If you have not customized those files you could -choose to not check them into your version control system (e.g. git). If that is -the case for your project it might be convenient to automatically run the -drupal-scaffold plugin after every install or update of your project. You can -achieve that by registering `@composer drupal:scaffold` as post-install and -post-update command in your composer.json: +plugin can download the scaffold files (like `index.php`, `update.php` etc.) to +the `web` directory of your project. If you have not customized those files you +could choose to not check them into your version control system (e.g. git). +If that is the case for your project, it might be convenient to automatically +run the drupal-scaffold plugin after every install or update of your project. +You can achieve that by registering `@composer drupal:scaffold` as `post-install` +and `post-update` command in your `composer.json`: ```json "scripts": { @@ -102,14 +107,14 @@ post-update command in your composer.json: }, ``` -### How can I apply patches to downloaded modules? +### How can I apply patches to included dependencies? -If you need to apply patches (depending on the project being modified, a pull -request is often a better solution), you can do so with the -[composer-patches](https://github.com/cweagans/composer-patches) plugin. +If you need to apply patches, you can do so with the +[composer-patches](https://github.com/cweagans/composer-patches) plugin included +in this project. -To add a patch to drupal module foobar insert the patches section in the extra -section of composer.json: +To add a patch to Drupal module `foobar`, insert the `patches` section in the +`extra` section of `composer.json`: ```json "extra": {