From 3068c0893b97d95578145904d34f3adb6e6e0ffb Mon Sep 17 00:00:00 2001 From: Alex Finnarn Date: Thu, 8 Feb 2024 13:32:30 -0500 Subject: [PATCH] add documentation --- .../custom/va_gov_content_release/README.md | 60 +++++++++++++++++++ .../src/Form/NextGitForm.php | 22 ++++--- .../va_gov_content_release.module | 6 -- 3 files changed, 75 insertions(+), 13 deletions(-) create mode 100644 docroot/modules/custom/va_gov_content_release/README.md delete mode 100644 docroot/modules/custom/va_gov_content_release/va_gov_content_release.module diff --git a/docroot/modules/custom/va_gov_content_release/README.md b/docroot/modules/custom/va_gov_content_release/README.md new file mode 100644 index 0000000000..b559ca78df --- /dev/null +++ b/docroot/modules/custom/va_gov_content_release/README.md @@ -0,0 +1,60 @@ +# VA.gov Content Release + +va.gov is built using two separate frontend systems with a third being built: + +- content-build - This is the frontend for generating static content files. You can read more about the project here: + https://github.com/department-of-veterans-affairs/content-build +- vets-website - This is the frontend for integrating React widgets. You can read more about the project here: + https://github.com/department-of-veterans-affairs/vets-website +- next-build - This is the new frontend for generating static content files. You can read more about the project here: + https://github.com/department-of-veterans-affairs/next-build + +In order to allow developers of the CMS to preview changes with different versions of the frontends, we have +developed an on-demand content release workflow that is primarily used on the Tugboat QA servers. + +## Content Build Releases + +The current static frontend "content-build" can be rebuilt using different versions of content-build and vets-website. + +1. Go to "/admin/content/deploy/git". +2. Check if the "Release State" in the "Status Details" block is set to "Ready". If it isn't then submitting the + form will do nothing. +2. Choose a version for content-build or leave at default. +3. Choose a version for vets-website or leave at default. +4. Click "Release content" to set the versions of content-build and vets-website as well as queue a + "va_gov_content_release_request" job. +5. The "va_gov_content_release_request" job will be triggered in the background from a service running + `scripts/queue_runner/queue_runner.sh` continuously. +6. The "va_gov_content_release_request" job will create a "va_gov_content_release_dispatch" job that ends up writing + a "buildrequest" file. +7. The continuously running `scripts/queue_runner/queue_runner.sh` script will look for the "buildrequest" file and + start a build if found. +8. Back on "/admin/content/deploy/git" you can view the build log via a link in the "Build log" section of the + "Status Details" block. +9. After the build completes, an event subscriber, `ContinuousReleaseSubscriber`, adds another job to the + "va_gov_content_release_request" queue if the build ran during business hours and continuous release is enabled in + settings. This keeps the build process going indefinitely. +10. View the frontend at the provided "Front end link" link in the "Status Details" block. + +There is a release state manager that can prevent any of these steps from happening, and you should check out the +`ReleaseStateManager` class for more information and details. There's a lot more to the process than what's outlined +above, but the above process should give you a rudimentary understanding of the way an on-demand release happens. + +## Next Build Releases + +The upcoming static frontend "next-build" can be rebuilt using different versions of next-build and vets-website. It +is a simpler process than the current content-build workflow. + +1. Go to "/admin/content/deploy/next_git". +2. If the form elements are disabled, then a lock file exists preventing another build from being triggered. You + can skip to step #6. +2. Choose a version for content-build or leave at default. +3. Choose a version for vets-website or leave at default. When content-build is releasing, these form fields might + be disabled. We can't change the vets-website version while another frontend build is running. +4. Click "Release Content" to set the versions of next-build and vets-website as well as write a "buildrequest" file. +5. A `scripts/queue_runner/next_queue_runner.sh` script continuously runs in the background looking for the + "buildrequest" file and then start a build if found. +6. Back on "/admin/content/deploy/git" you can view the build log via a link in the "Status" section of the + "Next Build Information" block. +7. Once the build completes no new build will be triggered until you click to release content again. +8. View the frontend at the provided "View Preview" link in the "Next Build Information" block. diff --git a/docroot/modules/custom/va_gov_content_release/src/Form/NextGitForm.php b/docroot/modules/custom/va_gov_content_release/src/Form/NextGitForm.php index 30a0d8fd55..e21180639d 100644 --- a/docroot/modules/custom/va_gov_content_release/src/Form/NextGitForm.php +++ b/docroot/modules/custom/va_gov_content_release/src/Form/NextGitForm.php @@ -7,6 +7,7 @@ use Drupal\Core\Form\FormStateInterface; use Drupal\Core\Site\Settings; use Drupal\Core\State\State; +use Drupal\va_gov_build_trigger\Service\ReleaseStateManager; use Drupal\va_gov_content_release\Frontend\Frontend; use Drupal\va_gov_content_release\Frontend\FrontendInterface; use Drupal\va_gov_content_release\FrontendVersion\FrontendVersionInterface; @@ -148,7 +149,7 @@ public function buildForm(array $form, FormStateInterface $form_state) { $form['build_request']['actions']['#type'] = 'actions'; $form['build_request']['actions']['submit'] = [ '#type' => 'submit', - '#value' => $this->t('Release content'), + '#value' => $this->t('Release Content'), '#button_type' => 'primary', ]; @@ -166,6 +167,13 @@ public function buildForm(array $form, FormStateInterface $form_state) { '#suffix' => '', ]; + // Lock the vets-website form fields if a content-build is in progress. + $build_status = $this->state->get('va_gov_build_trigger.release_state'); + if ($build_status !== ReleaseStateManager::STATE_READY) { + $form['build_request']['vets_website_selection']['#disabled'] = TRUE; + $form['build_request']['vets_website_git_ref']['#disabled'] = TRUE; + } + // Disable form changes and submission if a build is in progress. if (file_exists($this->fileSystem->realpath('public://' . self::LOCK_FILE_NAME))) { $form['build_request']['next_build_selection']['#disabled'] = TRUE; @@ -190,12 +198,12 @@ public function buildForm(array $form, FormStateInterface $form_state) { $last_build_time = $this->state->get('next_build.status.last_build_date', 'N/A'); $information = <<Status: $build_log_text

-

Lock file: $lock_file_text

-

Request file: $request_file_text

-

Next-build version: $next_build_version

-

Vets-website version: $vets_website_version

-

View preview: $view_preview

-

Last build time: $last_build_time

+

Lock File: $lock_file_text

+

Request File: $request_file_text

+

Next-build Version: $next_build_version

+

Vets-website Version: $vets_website_version

+

View Preview: $view_preview

+

Last Build Time: $last_build_time

HTML; $form['next_build_status']['information'] = [ diff --git a/docroot/modules/custom/va_gov_content_release/va_gov_content_release.module b/docroot/modules/custom/va_gov_content_release/va_gov_content_release.module deleted file mode 100644 index 35beaf8b98..0000000000 --- a/docroot/modules/custom/va_gov_content_release/va_gov_content_release.module +++ /dev/null @@ -1,6 +0,0 @@ -