add documentation

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.

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' => '</strong>',
     ];
 
+    // 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 = <<<HTML
       <p><strong>Status:</strong> $build_log_text</p>
-      <p><strong>Lock file:</strong> $lock_file_text</p>
-      <p><strong>Request file:</strong> $request_file_text</p>
-      <p><strong>Next-build version:</strong> $next_build_version</p>
-      <p><strong>Vets-website version:</strong> $vets_website_version</p>
-      <p><strong>View preview:</strong> $view_preview</p>
-      <p><strong>Last build time:</strong> $last_build_time</p>
+      <p><strong>Lock File:</strong> $lock_file_text</p>
+      <p><strong>Request File:</strong> $request_file_text</p>
+      <p><strong>Next-build Version:</strong> $next_build_version</p>
+      <p><strong>Vets-website Version:</strong> $vets_website_version</p>
+      <p><strong>View Preview:</strong> $view_preview</p>
+      <p><strong>Last Build Time:</strong> $last_build_time</p>
 HTML;
 
     $form['next_build_status']['information'] = [