diff --git a/README.md b/README.md index 2677db9..2d18b49 100644 --- a/README.md +++ b/README.md @@ -3,11 +3,7 @@ [![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/). - -> [!IMPORTANT] -> [Drupal 11 branch](https://github.com/drupal-composer/drupal-project/tree/11.x) is available! +**Based on [Drupal Composer](https://github.com/drupal-composer/drupal-project/tree/10.x)** ## What does the template do? @@ -22,203 +18,50 @@ dependencies with [Composer](https://getcomposer.org/). * Drush is installed for use as `vendor/bin/drush`. * Provides an [example](.env.example) of the `.env` file. -## Installing - -> [!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. - -Create your project: - -```bash -composer create-project drupal-composer/drupal-project:10.x-dev some-dir --no-interaction -``` - -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. - ## Usage +Manual install instructions. Production deployments should be handled by the CI/CD runner automatically. +*Instructions for this to come later one I've actually built the flow.* +> [!NOTE] +> The Cram-A-Lot website does not currently support containerized deployments. -### Adding new dependencies - -Use `composer require` to include and download dependencies for your project. - +1. Clone the repository to the destination. +2. Install Dependencies ```bash -cd some-dir -composer require drupal/devel +composer install ``` +3. Configure your webserver's home dir to `{PROJECT_DIR}/web` -By default, this project is set to install only stable releases of dependencies, -as specified by `"minimum-stability": "stable"` in `composer.json`. If you need -to use non-stable releases (e.g., `alpha`, `beta`, `RC`), you can modify the -version constraint to allow for such versions. For instance, to require a beta -version of a module: +### Setup for development +It is recommended to [install DDEV.](https://ddev.readthedocs.io/en/latest/users/install/ddev-installation/) +Review the official [Drupal Local Development Guide](https://www.drupal.org/docs/official_docs/local-development-guide) for more information. +### Prerequisites +You must have WSL2 set up on your system with docker installed. +### Install DDEV ```bash -composer require drupal/devel:1.0.0-beta1 +# Add DDEV’s GPG key to your keyring +sudo sh -c 'echo ""' +sudo apt-get update && sudo apt-get install -y curl +sudo install -m 0755 -d /etc/apt/keyrings +curl -fsSL https://pkg.ddev.com/apt/gpg.key | gpg --dearmor | sudo tee /etc/apt/keyrings/ddev.gpg > /dev/null +sudo chmod a+r /etc/apt/keyrings/ddev.gpg + +# Add DDEV releases to your package repository +sudo sh -c 'echo ""' +echo "deb [signed-by=/etc/apt/keyrings/ddev.gpg] https://pkg.ddev.com/apt/ * *" | sudo tee /etc/apt/sources.list.d/ddev.list >/dev/null + +# Update package information and install DDEV +sudo sh -c 'echo ""' +sudo apt-get update && sudo apt-get install -y ddev + +# One-time initialization of mkcert +mkcert -install ``` +### Starting the Dev Container +1. Clone this project, then open a terminal session to the new directory. +2. Run `ddev config --project-type drupal --docroot web` +3. Run `ddev composer install` then `ddev start`. Watch for the console to output a URL to access the webserver -Alternatively, you can globally adjust the stability settings by modifying -`composer.json` to include the desired stability level and explicitly allow it: - -```json -{ - "minimum-stability": "beta", - "prefer-stable": true -} -``` - -This configuration ensures that stable releases are preferred, but allows the -installation of non-stable packages when necessary. - -### Adding libraries - -You can manage front-end asset libraries with Composer thanks to the -[asset-packagist repository](https://asset-packagist.org/). Composer will detect -and install new versions of a library that meet the stated constraints. - -```bash -composer require bower-asset/dropzone -``` - -### Custom installation paths for libraries - -The installation path of a specific library can be controlled by adding it to -the `extra.installer-paths` configuration preceding `web/libraries/{$name}`. -For example, the `chosen` Drupal module expects the `chosen` library to be -located on `web/libraries/chosen`, but `composer require npm-asset/chosen-js` -installs the library into `web/libraries/chosen-js`. The following configuration -overrides installation it into the expected directory: - -```json -{ - "extra": { - "installer-paths": { - "web/libraries/chosen": [ - "npm-asset/chosen-js" - ], - "web/libraries/{$name}": [ - "type:drupal-library", - "type:npm-asset", - "type:bower-asset" - ] - } - } -} -``` - -For more details, see https://asset-packagist.org/site/about - -### 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`), -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 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`. -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`. -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. - -## FAQs - -### Should I commit the contrib modules I download? - -Composer recommends **no**. They provide [argumentation against but also -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` 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": { - "post-install-cmd": [ - "@composer drupal:scaffold", - "..." - ], - "post-update-cmd": [ - "@composer drupal:scaffold", - "..." - ] -}, -``` - -### How can I apply patches to included dependencies? - -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`: - -```json -"extra": { - "patches": { - "drupal/foobar": { - "Patch description": "URL or local path to patch" - } - } -} -``` - -### How do I specify a PHP version? - -There are 2 places where Composer will be looking for PHP version requirements -when resolving dependencies: -1. The `require.php` version value in `composer.json`. -2. The `config.platform` version value in `composer.json`. - -The purpose of `require.php` is to set the minimum PHP language requirements -for a package. For example, the minimum version required for Drupal 10.0 is -`8.0.2` or above, which can be specified as `>=8`. - -The purpose of `config.platform` is to set the PHP language requirements for the -specific instance of the package running in the current environment. For -example, while the minimum version required for Drupal 10 is `8.0.2` or above, -the actual PHP version on the hosting provider could be `8.1.0`. The value of -this field should provide your exact version of PHP with all 3 parts of the -version. - -#### Which versions to specify in my Drupal site? - -This project includes `drupal/core` which already has `require.php` added. Your -would inherit that constraint. There is no need to add `require.php` to your -`composer.json`. - -`config.platform` is a platform-specific. It is recommended to specify -`config.platform` as a _specific version_ (e.g.`8.1.19`) constraint to ensure -that only the package versions supported by your current environment are used. - -```json -"config": { - "platform": { - "php": "8.1.19" - } -}, -``` +## Contributing +If you're using this as a basis for a website, then please fork it first or change the origin after cloning. +Commits to the #main are blocked. Pull Requests will be rejected without good reason.