Documentation updates (#16253)

* Update Readmes

Fix some broken links

* Update documentation

* Update recommendations regarding forks vs branches

* Add links to some orphan docs

* Update documentation

* Update

* Move docs to vagov-team

* Move two files back

* Revert "Move docs to vagov-team"

This reverts commit fede8a7b05b74fca286d750d515b774a72679576.

Author: JunTaoLuo

README.md

@@ -1,6 +1,6 @@
 # VA.gov CMS
 
-This is the public/open documentation for the VA.gov Content Management System (CMS). The private/sensitive documentation is [here](https://github.com/department-of-veterans-affairs/va.gov-team-sensitive/tree/master/platform/cms). See [sensitive-guidance.md](https://github.com/department-of-veterans-affairs/va.gov-team/blob/master/platform/working-with-vsp/policies-work-norms/sensitive-guidance.md) to read about what should be public vs. private. We follow the U.S. Digital Services Playbook and [default to open/public](https://playbook.cio.gov/#play13)).
+This is the public/open documentation for the VA.gov Content Management System (CMS) for development, QA and DevOps topics. For product, design, support, research and cross-team documentation, visit the [platform/cms docs](https://github.com/department-of-veterans-affairs/va.gov-team/tree/master/platform/cms). For private/sensitive documentation, visit the [private docs repo](https://github.com/department-of-veterans-affairs/va.gov-team-sensitive/tree/master/platform/cms). See [sensitive-guidance.md](https://github.com/department-of-veterans-affairs/va.gov-team/blob/master/platform/working-with-vsp/policies-work-norms/sensitive-guidance.md) to read about what should be public vs. private. We follow the U.S. Digital Services Playbook and [default to open/public](https://playbook.cio.gov/#play13)).
 
 [VA.gov](https://www.va.gov) is constructed at the highest level by three projects:
 - the **CMS** or **Content Management System**, in this repository
@@ -29,6 +29,7 @@ The VA.gov CMS Team
    1. [WEB & CMS Integration](READMES/unity.md)
    1. [Workflow](READMES/workflow.md)
    1. [Project Conventions](READMES/project-conventions.md)
+   1. [Code Ownership](READMES/codeowners.md)
    1. [Environments](READMES/environments.md)
       1. [CI Environments](READMES/tugboat.md)
       1. [Local - DDEV](READMES/local.md)
@@ -45,26 +46,31 @@ The VA.gov CMS Team
    1. [Code Review](READMES/code-review.md)
    1. [Testing](READMES/testing.md)
    1. [Debugging](READMES/debugging.md)
-   1. [Comparing GraphQL Output](READMES/graph_ql.md)
+   1. [Comparing GraphQL Output](READMES/comparing-graphql-output.md)
+   1. [Dependabot Alerts](READMES/dependabot-alerts.md)
    1. [Dependabot Updates](READMES/dependabot-updates.md)
+   1. [Sentry](READMES/sentry.md)
+   1. [Profiling with Blackfire](READMES/blackfire.md)
+   1. [Scalability Testing](READMES/scalability-testing.md)
 1. **Release & Deployment**
    1. [The BRD System: Build, Release, Deploy](READMES/brd.md)
    1. [CMS Release Process](READMES/brd.md#cms-release-process)
    1. [CMS-CI Release Process (TODO)](READMES/brd.md#cmsci-release-process)
 1. **Architecture**
-   1. Overview
    1. Drupal
       1. [Memcache](READMES/drupal-memcache.md)
    1. [Content Models and Documentation](READMES/content-models.md)
       1. [Centralized Content](READMES/content-model-centralized-content.md)
    1. MetalSmith
+   1. [GraphQL](READMES/graph_ql.md)
    1. [Interfaces](READMES/interfaces.md) - APIs and Feature Flag
    1. Migrations (data imports)
       1. [Facility](READMES/migrations-facility.md)
       1. [Form](READMES/migrations-forms.md)
+   1. [Removing deprecated fields](READMES/remove-deprecated-fields.md)
    1. [Security](READMES/security.md)
    1. [Upstream Dependencies](READMES/upstream-dependencies.md)
-   1. [Downstream Dependencies](READMES/downstream-dependencies.md)
+   1. [Downstream Dependencies](READMES/downstream_dependencies.md)
 1. **CMS Users**
    1. [Login / SSOi](READMES/cms-login.md)
    2. [CMS User Notification Systems](READMES/cms-editor-notifications.md)
@@ -138,6 +144,7 @@ This section outlines only the systems utilized by the CMS. See the READMEs in t
 - A single "mirror" environment is regularly populated with a sanitized production database copy.
 - Open Pull Requests get environments created automatically, cloned from the "mirror" environment, with URLs like:
    - [pr123-{hash}.ci.cms.va.gov](https://pr123-{hash}.ci.cms.va.gov) for the CMS
+      - Cypress test logs and artifacts, see [Testing](READMES/testing.md) for details.
    - [web-{hash}.ci.cms.va.gov](http://web-{hash}.ci.cms.va.gov) for the frontend web build
    - [storybook-{hash}.ci.cms.va.gov](http://storybook-{hash}.ci.cms.va.gov) for design system documentation
 - Ad-hoc environments can be created and deleted at any time by any logged in user on [tugboat.vfs.va.gov/](https://tugboat.vfs.va.gov/):

READMES/alerts.md

@@ -4,7 +4,7 @@
 
 CMS Alerts are managed by [Sentry](https://sentry.vfs.va.gov/) and [DataDog](https://vagov.ddog-gov.com/).
 
-Runtime issues are reported to Sentry via the Raven module.
+[Runtime issues](READMES/sentry.md) are reported to Sentry via the Raven module.
 
 Various metrics in the CI/CD phases and at runtime are reported to DataDog.
 

READMES/blackfire.md

@@ -5,7 +5,7 @@ are used by PHP applications.  It can be used to measure the performance of a
 specific bit of code or an entire request.  This allows us to measure the
 performance impact of a code or platform change and debug performance issues.
 
-See also: 
+See also:
   * https://ddev.readthedocs.io/en/latest/users/debugging-profiling/blackfire-profiling
   * https://blackfire.io/docs/integrations/paas/ddev
   * https://blackfire.io/docs/up-and-running/installation (install instructions for non-DDEV environments)
@@ -69,9 +69,6 @@ Memory       3.62MB
 Network         n/a     n/a     n/a
 SQL          1.72ms     5rq
 ```
-## Credits
-
-The `blackfire-init.sh` script is based on [this gist](https://gist.github.com/tylerssn/8923149702d4a796c5e103412c2370c3) by @tylerssn.
 
 ----
 

READMES/codeowners.md

@@ -27,3 +27,7 @@ The important ideas are:
 6. Viewing the CODEOWNERS file in GitHub should provide debugging information.
 
 As with everything else in this project, CODEOWNERS is subject to continual refinement and development. Please raise issues and suggest improvements where appropriate.
+
+----
+
+[Table of Contents](../README.md)

READMES/comparing-graphql-output.md

@@ -50,3 +50,7 @@ jq -S '.data.nodeQuery.entities|=sort_by(.entityId)' pages2.json > pages3.json
 ```
 
 After processing both the "before" and "after" `pages.json` in this way, diffing the two should yield a far more useful visualization of the changes.
+
+----
+
+[Table of Contents](../README.md)

READMES/getting-started.md

@@ -13,31 +13,12 @@ See [the Codespaces README](./codespaces.md) to get a fully functional cloud-bas
 
 ## Step 1: Get Source Code / Git Setup
 
-- Fork the repo by pressing the "Fork" button: [github.com/department-of-veterans-affairs/va.gov-cms](https://github.com/department-of-veterans-affairs/va.gov-cms)
-- Clone your fork.
+- Clone the repo: [github.com/department-of-veterans-affairs/va.gov-cms](https://github.com/department-of-veterans-affairs/va.gov-cms)
   ```sh
-   $ git clone [email protected]:YOUR-GITHUB-USERNAME/va.gov-cms.git
+   $ git clone [email protected]:department-of-veterans-affairs/va.gov-cms.git
    $ cd va.gov-cms
   ```
 
-* Add upstream repo (Recommended):
-
-  ```sh
-  $ git remote add upstream [email protected]:department-of-veterans-affairs/va.gov-cms.git
-  ```
-* Optionally rename your fork so its name is more meaningful and ensures your upstream and origin are not misnamed.
-  ```sh
-  $ git remote rename origin myfork
-  ```
-* Verify your remotes, it should list upstream and myfork/origin as remotes.
-  ```sh
-  $ git remote -v
-
-  myfork  [email protected]:YOUR_GIT_USERNAME/va.gov-cms.git (fetch)
-  myfork  [email protected]:YOUR_GIT_USERNAME/va.gov-cms.git (push)
-  upstream        [email protected]:department-of-veterans-affairs/va.gov-cms.git (fetch)
-  upstream        [email protected]:department-of-veterans-affairs/va.gov-cms.git (push)
-  ```
 * Make sure your local repo is aware of what's on the remotes.
   ```sh
   $ git fetch --all
@@ -55,35 +36,35 @@ See [the Codespaces README](./codespaces.md) to get a fully functional cloud-bas
   $ git config --global branch.main.rebase true
   ```
 
-* Make branch main always pulls from the remote: upstream.
-  ```sh
-  $ git checkout main
-  $ git branch --set-upstream-to upstream/main
-  ```
-
 *  Make changes to simplesaml storage not be tracked locally.
 
   ```sh
    git update-index --skip-worktree samlsessiondb.sq3
   ```
 
-  You should periodically update your branch from `upstream main` branch:
+  You should periodically update your branch from `origin main` branch. This will rebase your current branch on top of new commits in main:
 
   ```sh
-   $ git pull upstream main
+   $ git pull origin main
   ```
 
 ## Step 2: Launch development environment
 
-1. [Install ddev](https://ddev.readthedocs.io/en/stable/#installation)
-2. Change into the project directory and run `ddev start`:
+1. Set ddev environment variables:
 
-   ```bash
-   $ cd va.gov-cms
-   $ ddev start
-   ```
+```bash
+$ cd va.gov-cms
+$ cp .env.example .env
+```
+
+2. [Install ddev](https://ddev.readthedocs.io/en/stable/#installation)
+3. Change into the project directory and run `ddev start`:
+
+```bash
+$ ddev start
+```
 
-The `ddev start` command will include the `composer install` command.
+The `ddev start` command will include the `composer install` command. Ensure that a CMS account is created and [Step 3](#step-3-sync-your-local-site-with-production-data) is run to sync login information before logging into the local CMS environment.
 
 See [Environments: Local](./local.md) for more information on ddev.
 
@@ -96,7 +77,7 @@ correct locations in your local development environment.
 
 - `ddev pull va `  or  `ddev pull va --skip-files`
 
-NOTE: This command downloads and impoorts the db followed by any configuration import.
+NOTE: This command downloads and imports the db followed by any configuration import.
 
 If you are not using ddev, the scripts will
 fail, but the files will still be available. The `sync-db.sh` script downloads the

READMES/github-workflows.md

@@ -23,3 +23,7 @@ Please follow the following guidelines:
 - If you need to check that a given workflow or action still triggers as expected, consider running the scripts `scripts/create-bad-test-files.sh` and `scripts/delete-bad-test-files.sh` to respectively create and delete files that can be used to test lints and checks.
 
 See ["Security hardening for GitHub Actions"](https://docs.github.com/en/actions/security-guides/security-hardening-for-github-actions) for more details concerning GitHub Actions and security.
+
+----
+
+[Table of Contents](../README.md)

READMES/analytics.md READMES/historical/analytics.md

@@ -14,15 +14,21 @@ If you see a message from your browser like the following:
 
 Click the "^" button and select "Keep."
 
-### OSX
-1. Open Keychain Access
-1. Go to Certificates (under Category in left sidebar)
-2. Select "System" under Keychains (in sidebar)
-3. Select "Import Items..." from File menu. (Shift-Command-I)
-4. Select the three .cer files above.
-5. They should now appear in your list of certificates
-6. For each certificate: 1) File > Get info  2) Under Trust > When using this certificate, select "Always Trust". 3) Close the Get info window, which will prompt a password save.
-7. You may need to restart your browser.
+### macOS (as of 13.4)
+1. Import the certificates.
+    1. Open Keychain Access
+    1. Select "System" under System Keychains (in sidebar)
+    <img src="images/macos-keychains.png" height="200">
+    1. Select "Import Items..." from File menu. (Shift-Command-I)
+    1. Select the three .cer files above.
+    1. They should now appear in your list of certificates under the "Keychain Access" view
+1. Trust each certificate.
+    1. For each of the three certificates, select it
+    1. File > Get info (Command-I)
+    1. Expand the "Trust" view
+    1. In the "When using this certificate" popup button, select "Always Trust".
+    1. Close the "Get Info" window, which will prompt a password save.
+1. You may need to restart your browser.
 
 ### Linux
 

READMES/https.md

@@ -63,6 +63,10 @@ and common calls look like:
 
 * Since this is a React widget displaying dynamic data it’s not using Metalsmith templates. The .jsx component files to support rendering are located in https://github.com/department-of-veterans-affairs/vets-website/tree/main/src/applications/facility-locator/components
 
+## JSON API
+
+See [JSON:API](jsonapi.md)
+
 ## Mirrors
 
 There are environments which exist in [Tugboat](tugboat.md) that provide a mirror of Prod.  The content and code are updated daily at 3am EST on the mirrors.  The list of mirrors can be found in the "[Mirrors (refreshed daily from PROD at 3am ET)](https://tugboat.vfs.va.gov/6042eeed6a89945a99399d3d)" project in tugboat.  Contact CMS Support in the #cms-support Slack channel to request a new mirror.

READMES/images/macos-keychains.png

@@ -4,8 +4,8 @@ This document will act as an in-repo collection of links while we attempt to boo
 
 All of this is very much in flux at present.
 
-- [CMS-QA Confluence Space](https://va-gov.atlassian.net/wiki/spaces/CMSQA/overview?homepageId=1814626528)
-  - [Strategy](https://va-gov.atlassian.net/wiki/spaces/CMSQA/pages/1814724630/Quality+Assurance+and+Testing+Strategy) -- an outline of the strategy we use to evaluate issues impacting QA, and how we address them in practice.
+- CMS-QA Confluence Space
+  - [Strategy](https://vfs.atlassian.net/wiki/spaces/~821090906/pages/2304933915/Quality+Assurance+and+Testing+Strategy) -- an outline of the strategy we use to evaluate issues impacting QA, and how we address them in practice.
   - [Current Challenges](https://va-gov.atlassian.net/wiki/spaces/CMSQA/pages/1812987905/Current+Challenges+Facing+the+Project) -- a survey of some of the more noteworthy QA challenges identified at this time, and how we're attempting to assess and deal with them.
 
 [Table of Contents](../README.md)

READMES/interfaces.md

@@ -1,18 +1,18 @@
 # Security
-1.  [Fortify Security Scans](testing.md#fortify-security-scans)
-2.  [PII](#pii)
+
+1.  [PII](#pii)
 
 ## PII
 
-The Content API has no PII or PHI on it and is a replacement for the public, open source [content repo](https://github.com/department-of-veterans-affairs/vagov-content). 
+The Content API has no PII or PHI on it and is a replacement for the public, open source [content repo](https://github.com/department-of-veterans-affairs/vagov-content).
 
-A sanitized database is available in a public S3 bucket (for open source development purposes) since all the configuration is already open source in [this repository](https://github.com/department-of-veterans-affairs/va.gov-cms/). 
+A sanitized database is available in a public S3 bucket (for open source development purposes) since all the configuration is already open source in [this repository](https://github.com/department-of-veterans-affairs/va.gov-cms/).
 
 The sanitized version removes all email addresses and resets to a commonly known development password.
 
 ## See Also
 
-- Our [security policy](/security/policy).
+- Our [security policy](/SECURITY.md).
 
 ----
 

READMES/qa.md

@@ -1,6 +1,6 @@
 # Sentry
 
-Sentry is used to track errors fom Drupal.  
+Sentry is used to track errors fom Drupal.
 
 URL: http://sentry.vfs.va.gov/
 * Login using your Github Login

READMES/security.md

@@ -17,15 +17,15 @@
 1. Write a manual to test ticket completion.
 
 ## Git
-To avoid cluttering up the repo with lots of branches, fork the repo and push your branches to your fork and make your pull request from your fork to the upstream repo. You can use the GitHub CLI, [`gh`](https://cli.github.com/), to make PRs from the command line much faster. Or after you push you will see a link in the output to ctrl + click and create a new PR from the branch you just pushed.  [Getting started](./getting-started.md).
+In this repo, we recommend working in individual branches and creating PRs to merge the branches to main. You can use the GitHub CLI, [`gh`](https://cli.github.com/), to make PRs from the command line much faster. Or after you push you will see a link in the output to ctrl + click and create a new PR from the branch you just pushed.  See [Getting started](./getting-started.md) for more details.
 
 ### Branches
 We are currently working off a single `main` branch. `main` is protected and requires both approval from code review and passing tests to be merged. Commits within pull requests are squashed and merged when they are accepted so that the only relate to one git commit, even if they originally contained multiple commits, the commit messages are added as a bulleted list so they are retained in the merge commit.
 
 ### Example Git workflow:
 
 1. `git fetch --all`
-1. `git checkout -b <VACMS-000-name> upstream/main`
+1. `git checkout -b <VACMS-000-name> origin/main`
 1. `ddev composer install`
 1. `ddev start` or `ddev restart`
 1. `ddev pull va --skip-files`  or `ddev pull va` idf you need managed files (images and pdfs)
@@ -34,15 +34,15 @@ We are currently working off a single `main` branch. `main` is protected and req
 1. Fix code formatting issues with CodeSniffer, Drupal standard (linters should run automatically upon trying to commit).
 1. Commit your changes. Each commit should be logically atomic (e.g. module adds in one commit, config in another, custom code in additional logical commits), and your commit messages should follow the pattern: "VACMS-123: A grammatically correct sentence starting with an action verb and ending with punctuation."
 _Example: VACMS-1234 Add configuration for menu reduction._
-1. Push work to your fork of the repository so a Pull Request may be created
-`git push myfork <branchname>`
+1. Push work in your branch to the remote repository so a Pull Request may be created
+`git push origin <branchname>`
 1. Once your PR is merged it will be automatically deployed to staging.cms.va.gov. If it is merged before 2:30pm ET and tests pass it will be in the daily, scheduled deploy to prod.cms.va.gov at 3:30pm ET.
 
   While working on your own branch, you may have to rebase it on main which will make it out of sync with your remote branch and will require you to force push to your branch.
 
 ### When is it ok to do a force push (-f)?
 
-  On the upstream repo, never.  On your own fork, it is perfectly acceptable to do force pushes.  If you have recently rebased your branch on main, you may have to do a force push to your fork.  When in doubt, ask in Slack.
+  It is never ok to force push to the main branch or an integration branch where other folks may be working from.  On your own branch, it is perfectly acceptable to do force pushes.  If you have recently rebased your branch on main, you may have to do a force push to your branch.  When in doubt, ask in Slack.
 
 ### Pull Request Norms
 * Pull requests should be made against the `main` branch.