From ceb550e294fecbdd415c42f18c452c1e7d7207f7 Mon Sep 17 00:00:00 2001 From: Amy Farrell Date: Thu, 21 Nov 2024 17:20:31 -0800 Subject: [PATCH 1/8] USAGOV-2101-add-codeowners: Add CODEOWNERS file, with benefits-finder contacts for that module --- docs/CODEOWNERS | 7 +++++++ 1 file changed, 7 insertions(+) create mode 100644 docs/CODEOWNERS diff --git a/docs/CODEOWNERS b/docs/CODEOWNERS new file mode 100644 index 0000000000..d540272f62 --- /dev/null +++ b/docs/CODEOWNERS @@ -0,0 +1,7 @@ +# See https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-code-owners + +# Benefits-finder tool team +web/modules/custom/usagov_benefit_finder geoffrey.queen@gsa.gov yuechen.chi@gsa.gov +config/sync/*bears* +config/sync/*benefit_* +config/sync/*benefits_finder* From c6506e14b808627eaff8416b31201e35e2aab9b0 Mon Sep 17 00:00:00 2001 From: Todd Blumenthal Date: Thu, 12 Dec 2024 15:18:35 -0500 Subject: [PATCH 2/8] USAGOV-2133-readme-improvements: init commit for README.md file --- README.md | 321 +++++++++++++----------------------------------------- 1 file changed, 77 insertions(+), 244 deletions(-) diff --git a/README.md b/README.md index 11890913c2..f32988b7c3 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ # USAgov 2021 -A revamped USA.gov site using Drupal 9 and Cloud Foundry +A revamped USA.gov site using Drupal 10 and Cloud Foundry @@ -12,43 +12,40 @@ A revamped USA.gov site using Drupal 9 and Cloud Foundry - [Setting Up the Project](#setting-up-the-project) - [Initialization](#initialization) - [Database Setup](#database-setup) - - [Media files Setup](#media-files-setup) + - [Media Files Setup](#media-files-setup) - [Access the Drupal Portal](#access-the-drupal-portal) - - [Automated tests Setup (cypress)](#automated-tests-setup-cypress)) - - [How to re-run the website](#how-to-re-run-the-website) - - [Using the terminal](#using-the-terminal) + - [Automated Tests Setup (Cypress)](#automated-tests-setup-cypress) + - [How to Re-run the Website](#how-to-re-run-the-website) + - [Using the Terminal](#using-the-terminal) - [Using Docker Desktop](#using-docker-desktop) - [Theme Lint Guidelines](#theme-lint-guidelines) - [Project Restart/Reset](#project-restartreset) - [Docker Cleanup](#docker-cleanup) - [Update Database](#update-database) - - [Starting on a new ticket](#starting-on-a-new-ticket) + - [Starting on a New Ticket](#starting-on-a-new-ticket) - [Continuing Work](#continuing-work) - [Tickets and Branching](#tickets-and-branching) - [Single Item Config Export](#single-item-config-export) - - [USAgovTheme](#usagovtheme) + - [USA.gov Theme](#usagovtheme) - [Export Database](#export-database) - [Export Config](#export-config) - [Import Config](#import-config) - - [Build and Deploy procedure](#build-and-deploy-procedure) + - [Build and Deploy Procedure](#build-and-deploy-procedure) - [Troubleshooting](#troubleshooting) - - [If cms password is not accepted:](#if-cms-password-is-not-accepted) - - [More info on Cloud Foundry \& Cloud.gov](#more-info-on-cloud-foundry--cloudgov) - + - [If CMS Password is Not Accepted:](#if-cms-password-is-not-accepted) + - [More Info on Cloud Foundry \& Cloud.gov](#more-info-on-cloud-foundry--cloudgov) ## Prerequisites -Before starting the project setup install/download the following: +Before starting the project setup, install/download the following: **Note: To download these tools, you must have administrator rights. If you do not have them and you're using a GSA computer, you can request admin rights [here](https://gsa.servicenowservices.com/sp/?id=sc_cat_item&sys_id=d75222fa1b9c641cb1f620eae54bcb20).** - * [Homebrew](https://docs.brew.sh/Installation) * [Git](https://formulae.brew.sh/formula/git#default) * [Php](https://formulae.brew.sh/formula/php#default) * [Composer](https://formulae.brew.sh/formula/composer#default) -* [Docket Desktop](https://docs.docker.com/desktop/install/mac-install/) -* [Drupal](https://www.digitalocean.com/community/tutorials/how-to-develop-a-drupal-9-website-on-your-local-machine-using-docker-and-ddev#step-1-mdash-installing-ddev) +* [Docker Desktop](https://docs.docker.com/desktop/install/mac-install/) * [jq](https://formulae.brew.sh/formula/jq#default) * [npm](https://radixweb.com/blog/installing-npm-and-nodejs-on-windows-and-mac) * An integrated development environment (IDE) such as [Visual Studio Code](https://code.visualstudio.com/download) @@ -58,54 +55,28 @@ Before starting the project setup install/download the following: ## Setting Up the Project ### Initialization - - Follow these steps when you first start working on the project, or anytime you want to reset your local development environment: - -**Note: Please wait until each command finishes before running the next. Expect long wait times. We recommend keeping your laptop (if you're using one) plugged in during this setup.** - +**Note: Please wait until each command finishes before running the next. Expect long wait times. Keep your laptop plugged in during this setup..** 1. Open a terminal and go to the project folder. - - -2. Run the these commands in the terminal: - - +2. Run these commands in the terminal: ``` bin/init docker compose up ``` - - Wait until messages stop scrolling by; the final message will probably be a message from node saying "Starting 'watch-sass' ..." - - 3. Open your browser and go to `localhost` (no port number needed). Initially, this will show an empty Drupal site. -**Note:** You should see logging messages in the terminal as the sote loads. This may take a minute. - - -[back to top](#usagov-2021) - +**Note:** You should see logging messages in the terminal as the site loads. This may take a minute. ### Database Setup - - Once you finish the previous section, follow these steps to set up your USAgov database: - 1. Download the latest SQL database available from [our Google Drive](https://drive.google.com/drive/folders/1zVDr7dxzIa3tPsdxCb0FOXNvIFz96dNx?usp=sharing). - - 2. Unzip the file and move the .sql file directly into the **root** of your USAgov project folder. - - 3. Open a new terminal and go to your USAgov project folder. - - 4. Run one of the following commands to populate the database from the SQL file you downloaded: - - If you sql file is titled `usagov.sql`, run this command: + If your SQL file is titled `usagov.sql`, run this command: ``` bin/db-update ``` @@ -115,136 +86,105 @@ Once you finish the previous section, follow these steps to set up your USAgov d bin/db-update usagov_other.sql ``` - **Note:** Expect a message saying there's no need to update the mariadb database. - -5. Reload the `localhost` page in your browser. You should now see the beta.usa.gov home page. - + **Note:** Expect a message saying there's no need to update the MariaDB database. +5. Reload `http://localhost` in your browser. You should now see the beta.usa.gov home page. [back to top](#usagov-2021) - -### Media files Setup - +### Media Files Setup Once you finish the previous section, you may not see the images on the site, please follow these steps to set up the media files: - 1. Download the latest ZIP file available from [our Google Drive](https://drive.google.com/drive/folders/1tI4k5qasEtmhxCBuznR3t0fe466milYk?usp=sharing). - - 2. Go to the **root** of your USAgov project folder in your IDE or preferred file manager system in your computer. - - 3. Locate the following folder: `s3/local/cms/public`. - - 4. Unzip the downloaded ZIP file and replace the current `s3/local/cms/public` folder with the one you just unzipped. 5. Reload the `localhost` page in your browser. You should now see the images on the site. - [back to top](#usagov-2021) ### Access the Drupal Portal To access the Drupal Portal to make any additional configurations, you will need to follow a few more steps. - 1. Generate a new URL to access your administrator account. - - ``` bin/drush uli ``` - - 2. The ***unique*** URL will be in some form of - `http://default/user/reset/1/123456789/ai6u4-iY1LgZFUjwVW2uXjh5jblqgsfUHGFS_U/login` +3. Replace the `default` portion with `localhost`. It should now be in the form: - Replace the the `default` portion with `localhost`. It should now be in the form: `http://localhost/user/reset/1/123456789/ai6u4-iY1LgZFUjwVW2uXjh5jblqgsfUHGFS_U/login` **Note:** This is a ONE-TIME login. +4. Adjust your credentials accordingly, so that you have a valid username/password combination to use for logging in to the Drupal portal going forward. You will need a valid username/password combination to provide to the Cypress tests, as well as for logging in to the Drupal portal directly. -3. Adjust your credentials accordingly, so that you have a valid username/password combination to use for logging in to the Drupal portal going forward. You will need a valid username/password combination to provide to the Cypress tests, as well as for logging in to the Drupal portal directly. +5. Navigate to [Admin -> People](http://localhost/admin/people), find your user account, and edit it to add a password. - Navigate to [Admin -> People](http://localhost/admin/people), find your user account, and edit it to add a password. +6. Log out as root, and log in with your own user account. - Log out as root, and log in with your own user account. +**Note:** You will need to repeat these steps any time you re-load the database from a backup. -**Note:** You will need to repeat these steps any time you re-load the database from a backup. - - -### Automated tests setup (cypress) +### Automated Tests Setup (Cypress) We use [Cypress](cypress.io). Note that we use only the Cypress App, _not_ Cypress Cloud! * Tests run in the `cypress` Docker container. * The tests themselves are in the `automated_tests/e2e-cypress` directory. -* Twig debugging will break some of the tests! Turn it off before running tests to get the most accurate results. - +* Twig debugging will break some of the tests! Disable it before running tests to get the most accurate results. -## Minimal setup for headless tests - -1. Supply Drupal *credentials* for the automated tests: Edit the file `env.local.cypress`. Supply a valid Drupal user name and password for `cypressCmsUser` and `cypressCmsPass`. - -2. Run `docker compose up` to (re-)create the cypress container with the new environment variables. +## Minimal Setup for Headless Tests +1. Supply Drupal *credentials* for the automated tests: Edit the file `env.local.cypress`. Supply a valid Drupal user name and password for `cypressCmsUser` and `cypressCmsPass`. +2. Run `docker compose up` to rebuild the cypress container with the new environment variables. 3. Run `bin/cypress-ssh` to open a shell in the cypress container You can run `npx cypress run --spec cypress/e2e` to run the entire test suite, or specify a smaller subset like `cypress/e2e/functional`. - The **Report** will be written to automated_tests/e2e-cypress/cypress/reports/html/index.html and you can open it in your web browser by navigating to that file and opening it. Cypress will report that it wrote the tests to /app/e2e-cypress/cypress/reports/html/index.html, which is the location of that file in the volume mounted to the cypress docker container. + The **Report** will be written to automated_tests/e2e-cypress/cypress/reports/html/index.html and you can open it in your web browser by navigating to that file and opening it. Cypress will report that it wrote the tests to /app/e2e-cypress/cypress/reports/html/index.html, which is the location of that file in the volume mounted to the cypress docker container. -Note: The first time you run bin/init, it will create the `env.local.cypress` file by copying `env.default.cypress`. The default `cypressBaseUrl` in that file should be correct for running tests against your local dev site. +Note: The first time you run `bin/init`, it will create the `env.local.cypress` file by copying `env.default.cypress`. The default `cypressBaseUrl` in that file should be correct for running tests against your local dev site. ## Setup for running Cypress interactively -You will need an X11 server on your computer, so that cypress can open a web browser in an X window you can interact with. +You will need an X11 server on your computer, so that Cypress can open a web browser in an X window you can interact with. ### On MacOS, install XQuartz This setup is based on information from these guides: -* https://www.cypress.io/blog/2019/05/02/run-cypress-with-a-single-docker-command#Interactive-mode -* https://sourabhbajaj.com/blog/2017/02/07/gui-applications-docker-mac/ +* [How to Run Cypress in Docker With a Single Command](https://www.cypress.io/blog/2019/05/02/run-cypress-with-a-single-docker-command#Interactive-mode) +* [Running GUI applications using Docker for Mac](https://sourabhbajaj.com/blog/2017/02/07/gui-applications-docker-mac/) This assumes you're using homebrew. -1. Check whether [XQuartz](xquartz.org) is already installed: - +1. Check whether [XQuartz](https://www.xquartz.org/) is already installed: ``` brew info xquartz ``` - - If XQuartz is already installed, continue with step 3. If you wind up changing any XQuartz settings, you should restart XQuartz, but you don't need to reboot. + If XQuartz is already installed, continue with step 3. Restart XQuartz if you make any changes to the settings, but rebooting is unnecessary. 2. If XQuartz is not installed, install it: - ``` brew install xquartz ``` - XQuartz will start up immediately. 3. From the XQuartz `Settings` menu, select `Security` and check (enable) `Allow connections from network clients`. The "network client" you're enabling this for is the virtual machine running in your cypress container. -4. Reboot your computer. (You need to reboot once after installing XQuartz. Thereafter, when you change your XQuartz settings you need to restart XQuartz, but not reboot.) - -Proceed to [Allow cypress to open an X window](#allow-cypress-to-open-an-x-window) +4. Reboot your computer. (You need to reboot once after installing XQuartz. Thereafter, when you change your XQuartz settings you need to restart XQuartz, but not reboot.) +Proceed to [Allow Cypress to open an X window](#allow-cypress-to-open-an-x-window) ### On Windows ... TODO - - -### Allow cypress to open an X window +### Allow Cypress to Open an X Window You'll need your local IP address. You're looking for the IP address of your machine on your local network, so it will probably start with `10.` or `192.168.`. This command will probably work: - ``` LOCAL_IP=$(ifconfig en0 | grep inet | awk '$1=="inet" {print $2}') echo $LOCAL_IP @@ -255,98 +195,63 @@ On a Mac, you can also find your IP Address in your Network Settings, or by hold Note that this address will change if you change networks, or if you disconnect and reconnect to the network 1. Allow connections from your IP address to open X windows: - ``` xhost $LOCAL_IP ``` - You should see a message like `10.0.0.200 being added to access control list`. (If you see `no DISPLAY is set`, that might mean you didn't reboot after installing XQuartz.) - 2. Edit `env.local.cypress`. The `DISPLAY` variable should be set to your local IP address with `:0` after it, for example, `DISPLAY=10.0.0.200:0` - -3. Run `docker compose up` to (re-)create the cypress container with the new environment variable. Alternatively, you can set the DISPLAY variable in the shell you get by running `bin/cypress-ssh`. - +3. Run `docker compose up` to rebuild the cypress container with the new environment variable. Alternatively, you can set the DISPLAY variable in the shell you get by running `bin/cypress-ssh`. [back to top](#usagov-2021) - -## How to re-run the website +## How to Re-run the Website There are two ways in which you can do this: - -### Using the terminal +### 1. Using the Terminal 1. Open Docker Desktop. - - 2. Open your USAgov project in your IDE. - - 3. Open a new terminal in your IDE. - - -4. Make sure you are located in the usagov-2021 folder. - - +4. Make sure you are located in the `/usagov-2021` directory. 5. Type the following command in your terminal: - - ``` docker compose up ``` - -### Using Docker Desktop +### 2. Using Docker Desktop 1. Open Docker Desktop. - - 2. Click on the section `Containers` located on the left panel. - - 3. Find the container called `usagov-2021`. - - 4. Click the play icon located in the column `Actions`. - [back to top](#usagov-2021) - ## Theme Lint Guidelines -If you make any changes to the `scss` or `js` files, make sure to check for linting errors nd resolve them before submitting a pull request. - +If you make any changes to the `scss` or `js` files, make sure to check for linting errors and resolve them before submitting a pull request. `bin/npm run lint` - [back to top](#usagov-2021) - ## Project Restart/Reset Sometimes, Docker problems arise after an upgrade and a more complete restart is needed. After closing down and destroying the existing containers, networks, and volumes the procedure is the same as the full project setup. - ### Docker Cleanup - - ``` docker compose down docker system prune ``` - -Refer to `Full Project Setup` section above to continue the setup. - +Refer to [Full Project Setup](#setting-up-the-project) section above to continue the setup. [back to top](#usagov-2021) - ## Update Database -Safe development database dumps are kept in Google Drive. You can download and import a SQL database from https://drive.google.com/drive/folders/1zVDr7dxzIa3tPsdxCb0FOXNvIFz96dNx?usp=sharing. - +Safe development database dumps are kept in Google Drive. You can download and import a SQL database from [our Google Drive](https://drive.google.com/drive/folders/1zVDr7dxzIa3tPsdxCb0FOXNvIFz96dNx?usp=sharing). Copy down the database you want by checking the date in the filename. For example: usagov_01_14_2022.sql.zip. -Unzip the file. It should be renamed to just usagov.sql. Place that uncompressed .sql file into the root of your repo. Then call the bin/db-update script. This could take over 10 mßinutes, so be patient. No messages are good. It will return you to the command prompt when it is done. - +Unzip the file. Rename it to usagov.sql. Place the uncompressed .sql file into the root of your repo. Then call the +`bin/db-update` script. This could take over 10 minutes, so be patient. No messages are good. It will return you to the +command prompt when it is done. 1. Download and Unzip the respective zip file 2. Move `usagov.sql` to the root of your project directory @@ -355,182 +260,126 @@ Unzip the file. It should be renamed to just usagov.sql. Place that uncompressed [back to top](#usagov-2021) ## Starting on a new ticket -When starting new work you may have to reset your database to a good starting point and make sure the current Drupal config is reflected in the site. - - +When starting new work you may have to reset your database to a good starting point and make sure the current Drupal +config is reflected in the site. ``` # Switch to stable starting point git checkout dev -git fetch git pull - # Reset db bin/db-update bin/drupal-update docker compose up - # Start new work git checkout -b USAGOV-###-new-feature-branch ``` - [back to top](#usagov-2021) - ## Continuing Work If you are returning to work on an existing feature branch you will need to make sure to update it with the latest changes from a fresh dev branch. It is also good practice to update any branch you are working on frequently. - - ``` -# switch out of feature branch and into dev branch -git checkout dev -git fetch -git pull - - -# switch back into feature branch -git checkout USAGOV-###-existing-feature-branch -git merge dev -docker compose up +# while working on your feature branch +git remote update +git pull origin dev +bin/drush cim ``` - [back to top](#usagov-2021) - ## Tickets and Branching -A branch name must be named after its associated Jira ticket. This is required for some parts of the automation to work. A Branch name must at minumum be USAGOV-###. You may optionally append a short lowercase dash-separated description to make things easier for humans to read. - +Branch names must follow the format of their associated Jira ticket to ensure proper functionality of automation processes. +At a minimum, a branch name should be in the format **USAGOV-###**. +Optionally, you can append a short, lowercase, dash-separated description to improve readability for humans. ex: USAGOV-123-short-ticket-name - If a ticket name is too long, you may shorten or even exclude the title, only the USAGOV-### prefix is required. - -We are using a git script to automatically add the current branch name to all commits in an effort to make all commit messages effortlessly reflect the task being worked on. This helps with automation. - - +We are using a git script to automatically add the current branch name to all commits in an effort to make all commit +messages effortlessly reflect the task being worked on. This helps with automation. ``` cp .git.commit-msg .git/hooks/commit-msg ``` - [back to top](#usagov-2021) - ## Single Item Config Export -If you have lots of junk or temporary config changes in your current database you may opt to only pick out the individual configs you know are needed. You can see the full list of available changes on the main Config Synchronize screen (/admin/config/development/configuration). Once you determine which config changes will be needed you can go to the Export > Single Item (/admin/config/development/configuration/single/export). There you can see and export just that one item. - - - +If you have lots of junk or temporary config changes in your current database you may opt to only pick out the individual configs you know are needed. +You can see the full list of available changes on the main [Config Synchronize screen](http://localhost/admin/config/development/configuration). +Once you determine which config changes will be needed you can go to the [Export > Single Item](http://localhost/admin/config/development/configuration/single/export). There you can see and export just that one item. [back to top](#usagov-2021) - ## USAgovTheme The USAgov theme is a subtheme of the USWDS_base theme. -This project's default start procedure (docker compose up) will start a container to automatically watch for changes and recompile the theme as needed. - +This project's default start procedure (`docker compose up`) will start a container to automatically watch for changes and recompile the theme as needed. The theme can be manually built at any time through gulp's build task. Any other gulp task can be triggered the same way. - - ``` # Rebuild theme bin/npm run build ``` - Any changes made to the node modules needed for building the theme will require a re-install of the node_modules before build. - - ``` # Reinstall node modules bin/npm install bin/npm run build ``` - - - This theme adds `USWDS_CKEditor_Custom_Styles.scss` into the CKeditor frame. - - - [back to top](#usagov-2021) - ## Export Database A helper script has been provided to perform exports. - - ``` bin/db-export ``` - You may specify a filename if you don't want to overwrite the default file location with a new export. - - ``` bin/db-export other-backup.sql ``` - This process asks drush to export the database for us since it does some cleanup work before running the export. - - - [back to top](#usagov-2021) - ## Export Config - 1. View differences * Configuration > Development > Configuration Synchronization * `/admin/config/development/configuration` 2. Export * via Command Line - a. `bin/drush cex` + - `bin/drush cex` * via Export Full Archive - a. Export > Full Archive - b. Move the desired configs into `/config/sync` + - [Export > Full Archive](http://localhost/admin/config/development/configuration/full/export) + - Move the desired configs into `/config/sync` * via Export Single Item - a. Export > Single Item - b. Find the config you want to sync - c. Create/Edit the file in `/config/sync` with the filename shown below the config textbox - d. Paste the config text into the file - e. Repeat for each desired config + - [Export > Single Item](http://localhost/admin/config/development/configuration/single/export) + - Find the config you want to sync + - Create/Edit the file in `/config/sync` with the filename shown below the config textbox + - Paste the config text into the file + - Repeat for each desired config 3. Commit config changes to git - - - [back to top](#usagov-2021) - ## Import Config - `bin/drush cim` - - - [back to top](#usagov-2021) - ## Build and Deploy procedure -Production ready containers can be built and deployed from a local environment. To do so, proper secrets must be entered into the env.local file as environmental variables. This same procedure is used by CircleCI and is defined in .circleci/config.yml - - - +Production ready containers can be built and deployed from a local environment. +To do so, proper secrets must be entered into the env.local file as environmental variables. +This same procedure is used by CircleCI and is defined in `.circleci/config.yml` ``` # uses env.local @@ -541,35 +390,19 @@ bin/cloudgov/space dev bin/cloudgov/deploy TAGNAME ``` - - - [back to top](#usagov-2021) - # Troubleshooting - ## If cms password is not accepted: -* run `bin/drush uli` -* copy the path of the url onto localhost in your browser's URL bar -* follow the prompts to reset the password - - -`Dockerfile-node` runs the gulp start command. - - - +* follow instructions found in [Access the Drupal Portal](#access-the-drupal-portal) [back to top](#usagov-2021) - ## More info on this project [Overview of selected documentation in this repo](README-overview.md) ## More info on Cloud Foundry & Cloud.gov - This repository was loosely based off of Cloud.gov's [cf-ex-drupal8 repo](https://github.com/cloud-gov/cf-ex-drupal8). Their README may provide other useful info. - From 896ef715fd555c2bb936263a853fdd544e0e6ea1 Mon Sep 17 00:00:00 2001 From: Todd Blumenthal Date: Thu, 12 Dec 2024 15:46:36 -0500 Subject: [PATCH 3/8] USAGOV-2133-readme-improvements: additional edits --- README.md | 38 +++++++++++++++++++++++--------------- 1 file changed, 23 insertions(+), 15 deletions(-) diff --git a/README.md b/README.md index f32988b7c3..cd2104cb3c 100644 --- a/README.md +++ b/README.md @@ -39,7 +39,7 @@ A revamped USA.gov site using Drupal 10 and Cloud Foundry Before starting the project setup, install/download the following: -**Note: To download these tools, you must have administrator rights. If you do not have them and you're using a GSA computer, you can request admin rights [here](https://gsa.servicenowservices.com/sp/?id=sc_cat_item&sys_id=d75222fa1b9c641cb1f620eae54bcb20).** +**Note:** To download these tools, you must have administrator rights. If you do not have them and you're using a GSA computer, you can request admin rights [here](https://gsa.servicenowservices.com/sp/?id=sc_cat_item&sys_id=d75222fa1b9c641cb1f620eae54bcb20). * [Homebrew](https://docs.brew.sh/Installation) * [Git](https://formulae.brew.sh/formula/git#default) @@ -57,7 +57,7 @@ Before starting the project setup, install/download the following: ### Initialization Follow these steps when you first start working on the project, or anytime you want to reset your local development environment: -**Note: Please wait until each command finishes before running the next. Expect long wait times. Keep your laptop plugged in during this setup..** +**Note:** Please wait until each command finishes before running the next. Expect long wait times. Keep your laptop plugged in during this setup. 1. Open a terminal and go to the project folder. 2. Run these commands in the terminal: @@ -66,7 +66,8 @@ Follow these steps when you first start working on the project, or anytime you w docker compose up ``` Wait until messages stop scrolling by; the final message will probably be a message from node saying "Starting 'watch-sass' ..." -3. Open your browser and go to `localhost` (no port number needed). Initially, this will show an empty Drupal site. +3. Open your browser and go to [http://localhost](http://localhost) (no port number needed). Initially, this will show an empty Drupal site. + **Note:** You should see logging messages in the terminal as the site loads. This may take a minute. ### Database Setup @@ -87,18 +88,18 @@ Once you finish the previous section, follow these steps to set up your USAgov d ``` **Note:** Expect a message saying there's no need to update the MariaDB database. -5. Reload `http://localhost` in your browser. You should now see the beta.usa.gov home page. +5. Reload `http://localhost` in your browser. You should now see the home page. [back to top](#usagov-2021) ### Media Files Setup -Once you finish the previous section, you may not see the images on the site, please follow these steps to set up the media files: +Once you finish the previous section, you may not see the images on the site. Please follow these steps to set up the media files: 1. Download the latest ZIP file available from [our Google Drive](https://drive.google.com/drive/folders/1tI4k5qasEtmhxCBuznR3t0fe466milYk?usp=sharing). 2. Go to the **root** of your USAgov project folder in your IDE or preferred file manager system in your computer. 3. Locate the following folder: `s3/local/cms/public`. -4. Unzip the downloaded ZIP file and replace the current `s3/local/cms/public` folder with the one you just unzipped. +4. Unzip the downloaded ZIP file and place the files inside the `s3/local/cms/public` directory. 5. Reload the `localhost` page in your browser. You should now see the images on the site. [back to top](#usagov-2021) @@ -115,12 +116,14 @@ To access the Drupal Portal to make any additional configurations, you will need `http://default/user/reset/1/123456789/ai6u4-iY1LgZFUjwVW2uXjh5jblqgsfUHGFS_U/login` -3. Replace the `default` portion with `localhost`. It should now be in the form: +3. Replace `default` with `localhost`. It should now be in the form: `http://localhost/user/reset/1/123456789/ai6u4-iY1LgZFUjwVW2uXjh5jblqgsfUHGFS_U/login` **Note:** This is a ONE-TIME login. -4. Adjust your credentials accordingly, so that you have a valid username/password combination to use for logging in to the Drupal portal going forward. You will need a valid username/password combination to provide to the Cypress tests, as well as for logging in to the Drupal portal directly. +4. Adjust your credentials accordingly, so that you have a valid username/password combination to use for logging into +the Drupal portal going forward. You will need a valid username/password combination to provide to the Cypress tests, +as well as for logging in to the Drupal portal directly. 5. Navigate to [Admin -> People](http://localhost/admin/people), find your user account, and edit it to add a password. @@ -130,7 +133,7 @@ To access the Drupal Portal to make any additional configurations, you will need ### Automated Tests Setup (Cypress) -We use [Cypress](cypress.io). Note that we use only the Cypress App, _not_ Cypress Cloud! +We use [Cypress](http://www.cypress.io). Note that we use only the Cypress App, _not_ Cypress Cloud! * Tests run in the `cypress` Docker container. * The tests themselves are in the `automated_tests/e2e-cypress` directory. @@ -138,15 +141,18 @@ We use [Cypress](cypress.io). Note that we use only the Cypress App, _not_ Cypre ## Minimal Setup for Headless Tests -1. Supply Drupal *credentials* for the automated tests: Edit the file `env.local.cypress`. Supply a valid Drupal user name and password for `cypressCmsUser` and `cypressCmsPass`. +1. Provide Drupal credentials for the automated tests by editing the env.local.cypress file. Enter a valid Drupal username and password values for the `cypressCmsUser` and `cypressCmsPass`. 2. Run `docker compose up` to rebuild the cypress container with the new environment variables. 3. Run `bin/cypress-ssh` to open a shell in the cypress container You can run `npx cypress run --spec cypress/e2e` to run the entire test suite, or specify a smaller subset like `cypress/e2e/functional`. - The **Report** will be written to automated_tests/e2e-cypress/cypress/reports/html/index.html and you can open it in your web browser by navigating to that file and opening it. Cypress will report that it wrote the tests to /app/e2e-cypress/cypress/reports/html/index.html, which is the location of that file in the volume mounted to the cypress docker container. + The **Report** will be written to `automated_tests/e2e-cypress/cypress/reports/html/index.html` and you can open it +in your web browser by navigating to that file and opening it. Cypress will report that it wrote the tests to +`/app/e2e-cypress/cypress/reports/html/index.html`, which is the location of that file in the volume mounted to the cypress docker container. -Note: The first time you run `bin/init`, it will create the `env.local.cypress` file by copying `env.default.cypress`. The default `cypressBaseUrl` in that file should be correct for running tests against your local dev site. +**Note:** The first time you run `bin/init`, it will create the `env.local.cypress` file by copying `env.default.cypress`. +The default `cypressBaseUrl` in that file should be correct for running tests against your local dev site. ## Setup for running Cypress interactively @@ -178,7 +184,7 @@ This assumes you're using homebrew. 4. Reboot your computer. (You need to reboot once after installing XQuartz. Thereafter, when you change your XQuartz settings you need to restart XQuartz, but not reboot.) -Proceed to [Allow Cypress to open an X window](#allow-cypress-to-open-an-x-window) +Proceed to [Allow Cypress to Open an X Window](#allow-cypress-to-open-an-x-window) ### On Windows ... TODO @@ -226,14 +232,16 @@ There are two ways in which you can do this: [back to top](#usagov-2021) ## Theme Lint Guidelines -If you make any changes to the `scss` or `js` files, make sure to check for linting errors and resolve them before submitting a pull request. +If you make any changes to the `scss` or `js` files, make sure to check for linting errors and resolve them before +submitting a pull request. `bin/npm run lint` [back to top](#usagov-2021) ## Project Restart/Reset -Sometimes, Docker problems arise after an upgrade and a more complete restart is needed. After closing down and destroying the existing containers, networks, and volumes the procedure is the same as the full project setup. +Sometimes, Docker problems arise after an upgrade and a more complete restart is needed. After closing down and +destroying the existing containers, networks, and volumes the procedure is the same as the full project setup. ### Docker Cleanup ``` From 980ef350f6a4c4c00a586816eafd2e47d169e83d Mon Sep 17 00:00:00 2001 From: Todd Blumenthal Date: Fri, 13 Dec 2024 09:44:48 -0500 Subject: [PATCH 4/8] USAGOV-2133-readme-improvements: final changes --- README.md | 9 ++++----- 1 file changed, 4 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index cd2104cb3c..0d9dea2343 100644 --- a/README.md +++ b/README.md @@ -88,7 +88,7 @@ Once you finish the previous section, follow these steps to set up your USAgov d ``` **Note:** Expect a message saying there's no need to update the MariaDB database. -5. Reload `http://localhost` in your browser. You should now see the home page. +5. Reload `localhost` in your browser. You should now see the home page. [back to top](#usagov-2021) @@ -141,7 +141,7 @@ We use [Cypress](http://www.cypress.io). Note that we use only the Cypress App, ## Minimal Setup for Headless Tests -1. Provide Drupal credentials for the automated tests by editing the env.local.cypress file. Enter a valid Drupal username and password values for the `cypressCmsUser` and `cypressCmsPass`. +1. Provide Drupal credentials for the automated tests by editing the `env.local.cypress` file. Enter a valid Drupal username and password values for the `cypressCmsUser` and `cypressCmsPass`. 2. Run `docker compose up` to rebuild the cypress container with the new environment variables. 3. Run `bin/cypress-ssh` to open a shell in the cypress container @@ -316,7 +316,7 @@ cp .git.commit-msg .git/hooks/commit-msg ## Single Item Config Export If you have lots of junk or temporary config changes in your current database you may opt to only pick out the individual configs you know are needed. -You can see the full list of available changes on the main [Config Synchronize screen](http://localhost/admin/config/development/configuration). +You can see the full list of available changes on the main [Config Synchronize page](http://localhost/admin/config/development/configuration). Once you determine which config changes will be needed you can go to the [Export > Single Item](http://localhost/admin/config/development/configuration/single/export). There you can see and export just that one item. [back to top](#usagov-2021) @@ -360,8 +360,7 @@ This process asks drush to export the database for us since it does some cleanup ## Export Config 1. View differences - * Configuration > Development > Configuration Synchronization - * `/admin/config/development/configuration` + * [Configuration > Development > Configuration Synchronization](http://localhost/admin/config/development/configuration) 2. Export * via Command Line - `bin/drush cex` From c7f89ed5772822d88672f5a02f5d267bf5c63131 Mon Sep 17 00:00:00 2001 From: Amy Farrell Date: Wed, 18 Dec 2024 13:48:53 -0800 Subject: [PATCH 5/8] USAGOV-2101-add-codeowners: Update codeowners and use github handles instead of email addresses --- docs/CODEOWNERS | 11 +++++++---- 1 file changed, 7 insertions(+), 4 deletions(-) diff --git a/docs/CODEOWNERS b/docs/CODEOWNERS index d540272f62..03bfec114a 100644 --- a/docs/CODEOWNERS +++ b/docs/CODEOWNERS @@ -1,7 +1,10 @@ # See https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-code-owners +# The CODEOWNERS file itself should have eyes on it. +docs/CODEOWNERS @akf @arpage + # Benefits-finder tool team -web/modules/custom/usagov_benefit_finder geoffrey.queen@gsa.gov yuechen.chi@gsa.gov -config/sync/*bears* -config/sync/*benefit_* -config/sync/*benefits_finder* +web/modules/custom/usagov_benefit_finder @scottqueen-bixal @gchi25 +config/sync/*bears* @scottqueen-bixal @gchi25 +config/sync/*benefit_* @scottqueen-bixal @gchi25 +config/sync/*benefits_finder* @scottqueen-bixal @gchi25 From 04a88e501047383580141c79da909fd0cbf1f537 Mon Sep 17 00:00:00 2001 From: Amy Farrell Date: Fri, 20 Dec 2024 14:55:47 -0800 Subject: [PATCH 6/8] USAGOV-2101-add-codeowners: Added more bf patterns, comments, and made a small syntax tweak --- docs/CODEOWNERS | 17 +++++++++++++++-- 1 file changed, 15 insertions(+), 2 deletions(-) diff --git a/docs/CODEOWNERS b/docs/CODEOWNERS index 03bfec114a..d3516ab4a9 100644 --- a/docs/CODEOWNERS +++ b/docs/CODEOWNERS @@ -1,10 +1,23 @@ +# Github uses the patterns in this file to automatically notify the specified users +# on pull requests that touch certain files. This does NOT mean that those users +# are required to review the pull request, or that they "own" the code. +# +# Users with write access to this repo are encouraged to use this file to +# "subscribe" to notifications about code they want to keep tabs on. +# # See https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-code-owners # The CODEOWNERS file itself should have eyes on it. docs/CODEOWNERS @akf @arpage -# Benefits-finder tool team -web/modules/custom/usagov_benefit_finder @scottqueen-bixal @gchi25 +# Benefits-finder tool team. +web/modules/custom/usagov_benefit_finder/ @scottqueen-bixal @gchi25 config/sync/*bears* @scottqueen-bixal @gchi25 config/sync/*benefit_* @scottqueen-bixal @gchi25 config/sync/*benefits_finder* @scottqueen-bixal @gchi25 +config/sync/core.entity_form_display.paragraph.b_* @scottqueen-bixal @gchi25 +config/sync/field.field.paragraph.b_* @scottqueen-bixal @gchi25 +config/sync/field.storage.paragraph.field_b_* @scottqueen-bixal @gchi25 +config/sync/paragraphs.paragraphs_type.b_* @scottqueen-bixal @gchi25 + + From cfe4695fe53c61d54ab60e6d982472c2394dee00 Mon Sep 17 00:00:00 2001 From: Amy Farrell Date: Fri, 20 Dec 2024 14:57:15 -0800 Subject: [PATCH 7/8] USAGOV-2101-add-codeowners: Add benefits-finder workflow actions to CODEOWNERS --- docs/CODEOWNERS | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/CODEOWNERS b/docs/CODEOWNERS index d3516ab4a9..64a0c15d2d 100644 --- a/docs/CODEOWNERS +++ b/docs/CODEOWNERS @@ -19,5 +19,6 @@ config/sync/core.entity_form_display.paragraph.b_* @scottqueen-bixal @gchi25 config/sync/field.field.paragraph.b_* @scottqueen-bixal @gchi25 config/sync/field.storage.paragraph.field_b_* @scottqueen-bixal @gchi25 config/sync/paragraphs.paragraphs_type.b_* @scottqueen-bixal @gchi25 +.github/workflows/*benefits-finder* @scottqueen-bixal @XavierMetichecchia From 7921e2bfca041362aa7d0932f28252c26a633b50 Mon Sep 17 00:00:00 2001 From: Todd Blumenthal Date: Mon, 23 Dec 2024 13:42:29 -0500 Subject: [PATCH 8/8] USAGOV-2133-readme-improvements: requested updates --- README.md | 94 ++++++++++++++++++++++++++----------------------------- 1 file changed, 44 insertions(+), 50 deletions(-) diff --git a/README.md b/README.md index a06682be3b..a881dc6870 100644 --- a/README.md +++ b/README.md @@ -71,7 +71,7 @@ Follow these steps when you first start working on the project, or anytime you w **Note:** You should see logging messages in the terminal as the site loads. This may take a minute. [back to top](#usagov-2021) -### Database Setup +### Database setup Once you finish the previous section, follow these steps to set up your USAgov database: 1. Download the latest SQL database available from [our Google Drive](https://drive.google.com/drive/folders/1zVDr7dxzIa3tPsdxCb0FOXNvIFz96dNx?usp=sharing). @@ -93,8 +93,7 @@ Once you finish the previous section, follow these steps to set up your USAgov d [back to top](#usagov-2021) -### Media Files Setup - +### Media files setup Once you finish the previous section, you may not see the images on the site. Please follow these steps to set up the media files: 1. Download the latest ZIP file available from [our Google Drive](https://drive.google.com/drive/folders/1tI4k5qasEtmhxCBuznR3t0fe466milYk?usp=sharing). @@ -106,42 +105,43 @@ Once you finish the previous section, you may not see the images on the site. Pl [back to top](#usagov-2021) -### Access the Drupal Portal -To access the Drupal Portal to make any additional configurations, you will need to follow a few more steps. +### Access the Drupal portal +There are two ways access the Drupal Admin Portal. + +## If you already have an account +1. Update your password + ``` + bin/drush upw my_name somePassword + ``` +2. After updating your password, you can sign in normally -1. Generate a new URL to access your administrator account. +## If you don't already have an account +1. Generate a one time, unique url to access your administrator account. ``` bin/drush uli ``` -2. The ***unique*** URL will be in some form of - - `http://default/user/reset/1/123456789/ai6u4-iY1LgZFUjwVW2uXjh5jblqgsfUHGFS_U/login` - -3. Replace `default` with `localhost`. It should now be in the form: +2. Replace `default` with `localhost`. It should now be in the form: `http://localhost/user/reset/1/123456789/ai6u4-iY1LgZFUjwVW2uXjh5jblqgsfUHGFS_U/login` - **Note:** This is a ONE-TIME login. -4. Adjust your credentials accordingly, so that you have a valid username/password combination to use for logging into +3. Adjust your credentials accordingly, so that you have a valid username/password combination to use for logging into the Drupal portal going forward. You will need a valid username/password combination to provide to the Cypress tests, as well as for logging in to the Drupal portal directly. -5. Navigate to [Admin -> People](http://localhost/admin/people), find your user account, and edit it to add a password. +4. Navigate to [Admin -> People](http://localhost/admin/people), find your user account, and edit it to add a password. -6. Log out as root, and log in with your own user account. +5. Log out as root, and log in with your own user account. **Note:** You will need to repeat these steps any time you re-load the database from a backup. -### Automated Tests Setup (Cypress) - +### Automated tests setup (Cypress) We use [Cypress](http://www.cypress.io). Note that we use only the Cypress App, _not_ Cypress Cloud! * Tests run in the `cypress` Docker container. * The tests themselves are in the `automated_tests/e2e-cypress` directory. * Twig debugging will break some of the tests! Disable it before running tests to get the most accurate results. -## Minimal Setup for Headless Tests - +## Minimal setup for headless tests 1. Provide Drupal credentials for the automated tests by editing the `env.local.cypress` file. Enter a valid Drupal username and password values for the `cypressCmsUser` and `cypressCmsPass`. 2. Run `docker compose up` to rebuild the cypress container with the new environment variables. 3. Run `bin/cypress-ssh` to open a shell in the cypress container @@ -149,18 +149,16 @@ We use [Cypress](http://www.cypress.io). Note that we use only the Cypress App, You can run `npx cypress run --spec cypress/e2e` to run the entire test suite, or specify a smaller subset like `cypress/e2e/functional`. The **Report** will be written to `automated_tests/e2e-cypress/cypress/reports/html/index.html` and you can open it -in your web browser by navigating to that file and opening it. Cypress will report that it wrote the tests to +in your web browser by navigating to that file. Cypress will report that it wrote the tests to `/app/e2e-cypress/cypress/reports/html/index.html`, which is the location of that file in the volume mounted to the cypress docker container. **Note:** The first time you run `bin/init`, it will create the `env.local.cypress` file by copying `env.default.cypress`. The default `cypressBaseUrl` in that file should be correct for running tests against your local dev site. ## Setup for running Cypress interactively - You will need an X11 server on your computer, so that Cypress can open a web browser in an X window you can interact with. ### On MacOS, install XQuartz - This setup is based on information from these guides: * [How to Run Cypress in Docker With a Single Command](https://www.cypress.io/blog/2019/05/02/run-cypress-with-a-single-docker-command#Interactive-mode) * [Running GUI applications using Docker for Mac](https://sourabhbajaj.com/blog/2017/02/07/gui-applications-docker-mac/) @@ -189,8 +187,7 @@ Proceed to [Allow Cypress to Open an X Window](#allow-cypress-to-open-an-x-windo ### On Windows ... TODO -### Allow Cypress to Open an X Window - +### Allow Cypress to open an X window You'll need your local IP address. You're looking for the IP address of your machine on your local network, so it will probably start with `10.` or `192.168.`. This command will probably work: ``` LOCAL_IP=$(ifconfig en0 | grep inet | awk '$1=="inet" {print $2}') @@ -211,10 +208,10 @@ Note that this address will change if you change networks, or if you disconnect [back to top](#usagov-2021) -## How to Re-run the Website +## How to re-run the website There are two ways in which you can do this: -### 1. Using the Terminal +### 1. Using the terminal 1. Open Docker Desktop. 2. Open your USAgov project in your IDE. 3. Open a new terminal in your IDE. @@ -232,7 +229,7 @@ There are two ways in which you can do this: [back to top](#usagov-2021) -## Theme Lint Guidelines +## Theme lint guidelines If you make any changes to the `scss` or `js` files, make sure to check for linting errors and resolve them before submitting a pull request. @@ -240,8 +237,7 @@ submitting a pull request. [back to top](#usagov-2021) -## Checking PHP Code style and syntax errors - +## Checking PHP dode style and syntax errors PHPCodesniffer and the parallel linting tools should be installed automatically on a local environment via `composer install`. PHPCodeSniffer is used to ensure new code follows Drupal's coding standard. The parallel linter will check for PHP syntax errors. If they detect any errors, they must be fixed before a PR of changes can be accepted. The following composer scripts are aliases for running these tools. @@ -257,11 +253,11 @@ The following composer scripts are aliases for running these tools. * Check for PHP lint errors `./bin/composer php-lint` -## Project Restart/Reset +## Project restart/reset Sometimes, Docker problems arise after an upgrade and a more complete restart is needed. After closing down and destroying the existing containers, networks, and volumes the procedure is the same as the full project setup. -### Docker Cleanup +### Docker cleanup ``` docker compose down docker system prune @@ -271,7 +267,7 @@ Refer to [Full Project Setup](#setting-up-the-project) section above to continue [back to top](#usagov-2021) -## Update Database +## Update database Safe development database dumps are kept in Google Drive. You can download and import a SQL database from [our Google Drive](https://drive.google.com/drive/folders/1zVDr7dxzIa3tPsdxCb0FOXNvIFz96dNx?usp=sharing). Copy down the database you want by checking the date in the filename. For example: usagov_01_14_2022.sql.zip. @@ -304,7 +300,7 @@ git checkout -b USAGOV-###-new-feature-branch [back to top](#usagov-2021) -## Continuing Work +## Continuing work If you are returning to work on an existing feature branch you will need to make sure to update it with the latest changes from a fresh dev branch. It is also good practice to update any branch you are working on frequently. ``` # while working on your feature branch @@ -315,7 +311,7 @@ bin/drush cim [back to top](#usagov-2021) -## Tickets and Branching +## Tickets and branching Branch names must follow the format of their associated Jira ticket to ensure proper functionality of automation processes. At a minimum, a branch name should be in the format **USAGOV-###**. Optionally, you can append a short, lowercase, dash-separated description to improve readability for humans. @@ -324,15 +320,15 @@ ex: USAGOV-123-short-ticket-name If a ticket name is too long, you may shorten or even exclude the title, only the USAGOV-### prefix is required. -We are using a git script to automatically add the current branch name to all commits in an effort to make all commit -messages effortlessly reflect the task being worked on. This helps with automation. -``` -cp .git.commit-msg .git/hooks/commit-msg -``` +As part of the ```bin/init``` process, we copy a Git hook script (```.git.commit-msg``` to ```.git/hooks/commit-msg```) +to automatically include the current branch name in all commit messages. This ensures that commit messages consistently +reflect the task being worked on, streamlining automation. + +**Note:** Any changes to these files will be overwritten the next time ```bin/init``` is run. [back to top](#usagov-2021) -## Single Item Config Export +## Single item config export If you have lots of junk or temporary config changes in your current database you may opt to only pick out the individual configs you know are needed. You can see the full list of available changes on the main [Config Synchronize page](http://localhost/admin/config/development/configuration). Once you determine which config changes will be needed you can go to the [Export > Single Item](http://localhost/admin/config/development/configuration/single/export). There you can see and export just that one item. @@ -360,7 +356,7 @@ This theme adds `USWDS_CKEditor_Custom_Styles.scss` into the CKeditor frame. [back to top](#usagov-2021) -## Export Database +## Export database A helper script has been provided to perform exports. ``` bin/db-export @@ -375,8 +371,7 @@ This process asks drush to export the database for us since it does some cleanup [back to top](#usagov-2021) -## Export Config - +## Export config 1. View differences * [Configuration > Development > Configuration Synchronization](http://localhost/admin/config/development/configuration) 2. Export @@ -395,16 +390,18 @@ This process asks drush to export the database for us since it does some cleanup [back to top](#usagov-2021) -## Import Config +## Import config `bin/drush cim` [back to top](#usagov-2021) -## Build and Deploy procedure -Production ready containers can be built and deployed from a local environment. +## Build and deploy procedure +Containers can be built and deployed to the dev environment or to the developer's sandbox space. To do so, proper secrets must be entered into the env.local file as environmental variables. -This same procedure is used by CircleCI and is defined in `.circleci/config.yml` +This same procedure is used by CircleCI and is defined in `.circleci/config.yml`. +The deployment procedures scripted for CircleCI include additional security measures. Developers should not deploy +into the production environment using the example commands below. ``` # uses env.local @@ -418,16 +415,13 @@ bin/cloudgov/deploy TAGNAME [back to top](#usagov-2021) # Troubleshooting - ## If cms password is not accepted: * follow instructions found in [Access the Drupal Portal](#access-the-drupal-portal) [back to top](#usagov-2021) ## More info on this project - [Overview of selected documentation in this repo](README-overview.md) ## More info on Cloud Foundry & Cloud.gov - This repository was loosely based off of Cloud.gov's [cf-ex-drupal8 repo](https://github.com/cloud-gov/cf-ex-drupal8). Their README may provide other useful info.