Merge branch 'develop' into YALB-1478--view-displays

docs/setup.md

@@ -1,10 +1,69 @@
 # Local Development Environment
 
-## Requirements
+__NOTE: Documentation assumes you are using MacOS with at least 8GB of memory on an Intel, M1, or M2 processor__
+
+:clap: Thank you for considering to contribute to the YaleSites Platform!
+
+## Requirements & Setup
+
+1. [Contact YaleSites](mailto:[email protected]?subject=Developer%20Access%20Request) for access to resources such as Pantheon, Figma designs, etc.
+2. [GitHub](#github)
+   1. SSH authorization key
+   2. [Github Package Personal Access Token](#package-personal-access-token) in environment variable `YALESITES_BUILD_TOKEN`
+3. [NVM](#additional-tools)
+4. [Node.js (>= 8.0, < 11.0)](#additional-tools)
+5. [Composer](#additional-tools): Version 2.x.
+6. [Terminus](#terminus): Machine auth token
+7. [Lando](#lando)
+8. Docker: Use the version Lando wants to install and increase memory resources to at least 3GB memory and 3 CPUs if possible
+9. [Project Setup](#project-setup)
+    ```bash
+    # Set up local development version of repo
+    git clone [email protected]:yalesites-org/yalesites-project
+    cd yalesites-project
+    npm run setup
+    ```
+10. [Project Commands](#project-commands)
+
+## Repository Links
+
+Repositories used to make the platform:
+
+* [Yalesites Project](https://github.com/yalesites-org/yalesites-project): Drupal Platform Site (This repo)
+   * [Yalsites Project Profile modules](https://github.com/yalesites-org/yalesites-project/tree/develop/web/profiles/custom/yalesites_profile/modules/custom): Each subdirectory should have a README describing the function
+* [Atomic Theme](https://github.com/yalesites-org/atomic): Atomic Drupal Theme bridging the Drupal site and the component library
+* [Component Library Twig](https://github.com/yalesites-org/component-library-twig): Component Library
+   * [Deployed Storybook](https://yalesites-org.github.io/component-library-twig)
+* [Tokens](https://github.com/yalesites-org/tokens): Style tokens from Figma used to drive design of the platform and components
+* [ESLint Config and Other Formatting](https://github.com/yalesites-org/eslint-config-and-other-formatting): Reusable Linting/Formatting included in the project
+
+## Requirement Details
+
+### GitHub
+
+While the project can be cloned and run locally without it, one must setup an SSH key on their development machine if they wish to push code on any of the yalesites repositories.
+Luckily, [GitHub has an intuitive guide on how to setup an SSH key on your machine and register it with your GitHub Account](https://docs.github.com/en/authentication/connecting-to-github-with-ssh/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent)
+
+#### Package Personal Access Token
+
+Each environment that needs to pull @yalesites-org packages from GitHub needs to be authenticated using a "Personal Access Token". This only needs to be done once per-environment.
+
+- Go to `https://github.com/settings/tokens/new`
+  - In the "Note" field add something like "YaleSites GitHub Packages"
+  - Choose an expiration value
+  - Check the box for "write:packages" (this will automatically check all of the "repo" boxes as well)
+  - Click "Generate token"
+- On your local machine, create an environment variable. This process varies depending on the shell and operating system you use. It will be something similar to this though: `export KEY=value`.
+  - The `key` for YaleSites projects needs to be `YALESITES_BUILD_TOKEN`
+  - The `value` is the token you created above
+- Done!
+
+- [Here's a stack overflow post showing how to set persistent environment variables for various shells](https://unix.stackexchange.com/questions/117467/how-to-permanently-set-environmental-variables)
+
 
 ### Terminus
 
-Pantheon's Terminus is an almost-essential command-line tool for managing sites. The CLI is required to run many of the scripts for building, updating, and deploying changes between the local development environment and the Pantheon platform.
+Pantheon's Terminus is a command-line tool for managing sites. The CLI is required to run many of the scripts for building, updating, and deploying changes between the local development environment and the Pantheon platform.
 
 1. [Install Terminus](https://pantheon.io/docs/terminus/install/)
 2. [Setup a valid machine token](https://pantheon.io/docs/machine-tokens)
@@ -21,52 +80,25 @@ This project supports development with Lando using the Pantheon recipe. This pro
 3. [Setup local certificate authority](https://docs.devwithlando.io/config/security.html)
 4. Increase Docker resources: Locate the 'Resources' section in your Docker preferences. For most architectures, this project requires at least 3GB of memory and 3 CPUs. Additional CPUs and memory may be helpful but should stay under the halfway mark of your total available resources. Also disable the _'Start Docker when you log in'_ setting under the 'General' tab.
 
-### GitHub
-While the project can be checked out and run locally without it, one must setup an SSH key on their development machine if they wish to push code on any of the yalesites repositories.
-Luckily, [GitHub has an intuitive guide on how to setup an SSH key on your machine and register it with your GitHub Account](https://docs.github.com/en/authentication/connecting-to-github-with-ssh/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent)
-
 ### Additional tools
 
-- [Composer](https://getcomposer.org/download/): PHP package manager. Version 2.x.
-- [NVM](https://github.com/nvm-sh/nvm#install--update-script): Recommended for installing and switching between Node versions.
-- Node.js (>=8.0). We recommend installing via NVM.
+- [Composer](https://getcomposer.org/download/): PHP package manager. Version 2.x. (Can use lando instead if you prefer)
+- [NVM](https://github.com/nvm-sh/nvm#install--update-script): Node Version Manager
+- Node.js (>=8.0,<11.0). Via NVM.
 
-## Project setup script
+### Cloning the project
 
-This repository contains a custom Pantheon Upstream used to create and manage every site on the YaleSites platform. Out of the box this project is not connected to an individual Drupal site. To contribute to this project, we need to connect the local development environment to a Drupal site to leverage the site's files and database.
+To clone the project, the above requirements must be met first.  If you have not already cloned the repository:
 
-```bash
-# Executing the setup script will prepare the local development environment.
-npm run setup
-```
-
-## Alternative manual setup instructions
-
-A detailed explanation of the setup script appears below.
-
-```bash
-# Step 1: Clone this repository and enter the project directory.
-git clone https://github.com/yalesites-org/yalesites-project.git
-cd yalesites-project
-
-# Step 2: Ignore the composer.lock file on local dev only.
-grep -qxF 'composer.lock' .git/info/exclude || echo 'composer.lock' >> .git/info/exclude
-```
+`git clone [email protected]:yaleitsites-org/yalesites-project.git`
 
-The Pantheon Lando recipe can connect the local development environment to a remotely hosted site. Connection information is stored in a local Lando settings file and includes a Pantheon site name and UUID. While we can connect to any site running this upstream, a particular integration environment has been provisioned for engineers working on this repository or the associated YaleSites profile. Connection information for the integration environment is stored in the example Lando local file.
+## Project setup
 
-```bash
-# Step 3: Create a local Lando settings file to connect to the external environment.
-cp .lando.local.example.yml .lando.local.yml
-```
-
-Starting Lando will provision the containers required to run a local development environment. The `pull` command can then sync the database and files from a Pantheon-hosted site with the new local site.
+This repository is a Pantheon Custom Upstream used to create and manage every site on the YaleSites platform. Out of the box this project is not connected to an individual Drupal site. To contribute to this project, we need to connect the local development environment to a Drupal site to leverage the site's files and database.
 
 ```bash
-# Step 4: Start Lando and import the remote files and database.
-lando start
-lando pull --database=dev --files=dev --code=none
-lando drush cr
+# Executing the setup script will prepare the local development environment.
+npm run setup
 ```
 
 Visit the local dev site [https://yalesites-project.lndo.site/](https://yalesites-project.lndo.site/) or run `lando drush uli` to obtain a login link.
@@ -77,7 +109,7 @@ _The steps in this section are completed in the aforementioned setup script._
 
 The YaleSites platform organizes work across a series of custom modules, themes, and an installation profile. To avoid an unnecessarily monolithic architecture, each of these dependencies exist in unique repositories that are included via composer. The previously created local development environment is an ideal place for working on these projects within the context of a YaleSite.
 
-By default, composer dependencies are downloaded in a dist packaged version of the project with git metadata removed. When working on a Yale-managed package, the originally downloaded composer dependency must be replaced with the source packaged version. This allows any changes to be tracked in version control.
+By default, composer dependencies are downloaded in a dist packaged version of the project with git metadata removed. When working on a Yale-managed package such as Atomic or the Component Library, the originally downloaded composer dependency must be replaced with the source packaged version. This allows any changes to be tracked in version control.
 
 ### Atomic theme
 
@@ -100,3 +132,55 @@ git -C web/themes/contrib/atomic ls-remote --get-url
 # Step 5: Setup npm linked packages for theme dependencies
 npm run local:theme-link
 ```
+
+## Project Commands
+
+__NOTE: There are more commands, but these are those that current developers feel are most used.__
+
+### NPM
+
+```bash
+npm run setup                                   # Setup whole environment
+```
+```bash
+npm run build-with-assets                       # Build/Rebuild with replaced assets
+```
+```bash
+npm run build-with-install                      # Rebuild with fresh imports
+```
+```bash
+npm run local:git-checkout                      # Sync:
+                                                #   yalesites-project: develop branch
+                                                #   atomic: main branch
+                                                #   component-library: main branch
+                                                #   tokens: main branch
+```
+```bash
+npm run local:git-checkout -- -h                # More command help
+```
+```bash
+npm run confex                                  # Export drupal configuration
+```
+```bash
+npm run confim                                  # Import drupal configuration
+```
+```bash
+npm run db:get                                  # Download a dev database locally from a pantheon site
+```
+```bash
+npm run files:get                               # Download dev files locally from a pantheon site
+```
+```bash
+npm run lint                                    # Lints js, php, and styles
+```
+```bash
+npm run fix:js                                  # Fixes js linting errors if possible
+```
+```bash
+npm run test                                    # Runs prettier and linting
+```
+
+### Composer
+```bash
+lando composer code-sniff                       # Test for PHP linting issues that CI tests against
+```

web/profiles/custom/yalesites_profile/modules/custom/ys_alert/README.md

@@ -1,4 +1,4 @@
-# YaleSites Starterkit
+# YaleSites Alert
 
 This module creates an alert banner to display a message across all pages of a
 YaleSite. A backend interface allows site owners to enable or disable alerts.

web/profiles/custom/yalesites_profile/modules/custom/ys_captcha/README.md

@@ -1,4 +1,4 @@
-# YaleSites reacptcha
+# YaleSites Recaptcha
 
 This module customizes recaptcha settings for the YaleSites platform.
 

web/profiles/custom/yalesites_profile/modules/custom/ys_themes/README.md

@@ -1,4 +1,4 @@
-# YaleSites Starterkit
+# YaleSites Themes
 
 This module is used to support YaleSites themes. This includes functionality
 that allows site owners to override global theme settings.