DIGITAL-287: Update README with suggested improvements

GSA · Jan 3, 2025 · 770b201 · 770b201
1 parent 660cac4
commit 770b201
Show file tree

Hide file tree

Showing 2 changed files with 89 additions and 12 deletions.
diff --git a/README.md b/README.md
@@ -6,28 +6,83 @@ See our [CONTRIBUTING.md](CONTRIBUTING.md) for Git configuration and working wit
 
 ### Contents
 
-- [Software Requirements](#software-requirements)
-- [Getting Starting](#getting-started)
-- [Additional Reading](#additional-reading)
+- [Software requirements](#software-requirements)
+- [QuickStart installation](#quickstart-installation)
+- [Additional developer documentation](#additional-developer-documentation)
 
-## Software Requirements
+## Software requirements
 
 * PHP 8.3: Used to run `./robo.sh` / `./composer.sh` tasks
 * Composer Version 2: https://getcomposer.org/, much faster to run composer locally than through docker
 * Lando: https://lando.dev/download/
 
-## Getting Started
+See our [Install Help documentation](docs/install-help.md) for help with installing the PHP and Composer
+requirements locally.
 
-The local environment is configured to use the [Lando Drupal Plugin](https://docs.lando.dev/plugins/drupal/getting-started.html). However, you cannot just `lando start` the first time you start the site. Instead, please `./robo.sh lando:init`. Following that, you can interact with the environment like a normal Lando site.
+## QuickStart installation
+
+The local environment is configured to use
+the [Lando Drupal Plugin](https://docs.lando.dev/plugins/drupal/getting-started.html). However, you cannot
+just `lando start` the first time you start the site.
+
+Once you have confirmed that you have PHP 8.3 and Composer 2 installed locally run the follows CLI commands to get your
+site running locally.
+
+```
+composer install
+./robo.sh lando:init
+# Installing a Drupal site from config (no DB needed).
+lando si
+```
+
+Following that, you can interact with the environment like a normal Lando site using standard `lando` commands.
+
+## Working with the codebase
 
 There is some custom functionality apart from what's in the base Lando installation.
-* Installing a Drupal site from config (no DB needed): `lando si`
-* If switching to a new branch, always: `lando rebuild -y && lando si` to start off completely fresh.
+
 * See a list of shortcuts (Drush, Composer, etc.): `./robo.sh common:shortcuts-help`
-* Use `./composer.sh` instead of `composer` or `lando composer`. `./composer.sh` will cause entries `composer.log` to be made so we can replay composer commands on conflicts.
-* Sign in as admin: `./drush.sh uli`.
-* Export content as configuration `./robo.sh drupal-project:export-content`. See [Exporting Content as Configuration](#exporting-content-as-configuration).
+* When switching to a new branch, always: `lando rebuild -y && lando si` to start off completely fresh.
+* Export content as configuration `./robo.sh drupal-project:export-content`.
+  See [Exporting Content as Configuration](docs/backend#exporting-content-as-configuration).
+
+### Compiling theme assets
+
+See our [Frontend documentation](docs/frontend.md) for working with the `digital_gov` custom theme.
+
+## Basic composer commands
+Instead of using `lando composer` we use `./composer.sh` which generate entries in `composer.log` so we can replay composer commands on conflicts.
+
+| **Command**                                  | **Use case**                |
+|----------------------------------------------|-----------------------------|
+| `./composer.sh require drupal/<MODULE_NAME>` | Download a drupal module    |
+| `./composer.sh remove drupal/<MODULE_NAME>`  | Remove a drupal module      |
+| `./composer.sh update --lock`                | Import Drupal configuration |
+
+## Basic Drush commands
+
+| **Command**       | **Use case**                 |
+|-------------------|------------------------------|
+| `lando drush cr`  | Clearing Drupal cache        |
+| `lando drush uli` | Log into Drupal as superuser |
+| `lando drush cim` | Import Drupal configuration  |
+| `lando drush cex` | Export Drupal configuration  |
+
+## Lando commands
+
+| **Command**     | **Use case**                                         |
+|-----------------|------------------------------------------------------|
+| `lando start`   | Start the container                                  |
+| `lando stop`    | Stop the container                                   |
+| `lando rebuild` | Rebuild the container (retains your db)              |
+| `lando destroy` | Destroys container and your db (when all else fails) |
+
+## Custom Lando commands
+
+| **Command** | **Use case**                                    |
+|-------------|-------------------------------------------------|
+| `lando si`  | Install a fresh Drupal site from configuration. |
 
-## Additional Reading
+## Additional developer documentation
 
 Please take a look at the `./docs` directory for more information.
diff --git a/docs/install-help.md b/docs/install-help.md
@@ -0,0 +1,22 @@
+# Install PHP & Composer using homebrew
+
+## Install PHP 8.3
+Follow these steps to download php. You will download the base php package then install and reset to version 8.3.
+```
+brew install php
+brew install php@8.3
+# Change the version number in the following command to match the base php version number.
+# To find the base version number run `php -v`
+brew unlink php@8.4
+brew link php@8.3
+# Add path to zshrc for global access to 8.3 using php
+echo 'export PATH="/opt/homebrew/opt/php@8.3/bin:$PATH"' >> ~/.zshrc
+echo 'export PATH="/opt/homebrew/opt/php@8.3/sbin:$PATH"' >> ~/.zshrc
+```
+Confirm your version of php by opening a new terminal and running `php -v`.
+
+## Install Composer 2.0
+```
+brew install composer
+```
+Confirm composer version using `composer -v`.