Front end sites v1 pipeline docs updates

source/content/guides/decoupled/overview/02-considerations.md

@@ -43,18 +43,11 @@ The following components are required for your backend, especially if using the
      - [Composer](https://getcomposer.org/) - Composer is a tool for dependency management in PHP. It allows you to declare libraries for your project and manages them for you.
      - [Terminus](/terminus) - The command-line interface which provides advanced interaction with Pantheon. Terminus is needed to update build tools for a Front-End Site.
 
-## Frontend Requirements
+## Front-End Requirements
 
-The following components are required for your frontend project to use Pantheon's Front-End Sites:
+As of the release of our [V1 build pipeline](/guides/decoupled/overview/v1-pipeline), Front-End Sites runs can run v16, v18, or v20 of Node.js [as specified in your `package.json` file](/guides/decoupled/overview/manage-settings#nodejs-version).
 
-- [Node.js](https://nodejs.org/en/)
-  - Supported Node.js versions for static sites (Gatsby): 14, 16, 18.
-  - Supported Node.js versions for dynamic sites (Next.js): 16.
-  - Installing [nvm](https://heynode.com/tutorial/install-nodejs-locally-nvm/) using Homebrew is recommended for Mac users.
-
-## Frontend Frameworks
-
-Pantheon Front-End Sites Early Access (EA) program currently supports Gatsby and Next.js as frontend frameworks. Additional frameworks will be added to our official support list over the coming months.
+Pantheon Front-End Sites Early Access (EA) program currently supports Gatsby and Next.js as frameworks. Additional frameworks will be added to our official support list over the coming months.
 
 You can use frontend frameworks other than Gatsby and Next.js, however the process requires manual configuration. Refer to [Use a Non-official Framework](/guides/decoupled/no-starter-kit/any-framework) for specific instructions.
 
@@ -163,4 +156,4 @@ We recommend that you use proxy search requests to [Solr](/solr) instances on th
 ## More Resources
 
 - [Multidev](/guides/multidev)
-- [Use a Non-official Front-End Sites Framework](/guides/decoupled/no-starter-kit/any-framework)
+- [Use a Non-official Front-End Sites Framework](/guides/decoupled/no-starter-kit/any-framework)

source/content/guides/decoupled/overview/05-manage-settings.md

@@ -31,13 +31,36 @@ You can change the Site Name, connect or disconnect your Git repository, and del
 
 ### Node.js Version
 
-Pantheon respects the setting in `.nvmrc` when selecting the Node.js version for runtime. Currently supported versions are:
+As of the release of our [V1 build pipeline](/guides/decoupled/overview/v1-pipeline), Front-End Sites runs can run v16, v18, or v20 of Node.js as specified in your `package.json` file.
+
+[Odd-numbered Node.js releases, such as v17, never enter "Active LTS" status](https://nodejs.org/en/about/previous-releases#previous-releases). They are not available on Pantheon.
+
+Pantheon inspects the engines field in `package.json` when selecting a specific Node.js version for the build (Gatsby.js and Next.js) and runtime (Next.js) of your Front-End Site. For example, to select Node.js 16 for a given deployment, you should do the following:
+
+```json:title=package.json
+"engines": {
+  "node": ">=16.0.0 <18.0.0"
+},
+```
+
+To break down that example, the `package.json` file for the project declares it expects something greater than or equal to 16.0.0 and less than 18.0.0. As of the writing of this documentation, this declaration would result in 16.20.2 being used.
+
+Note that if you select a range of major Node.js versions, Pantheon will select the most recent Node.js major version for that deployment. For example, the following configuration would result in Node.js 18.x being selected:
+
+```json
+"engines": {
+  "node": ">=16.0.0 <20.0.0"
+},
+```
+We recommend that when you need to change the version of Node.js for your Front-End Site, that you test the new version by pushing the updated `package.json` to a branch first and create a pull request. Pantheon will create an environment for your site specific to that pull request.
+
+Sites made prior to **November 13th, 2023** set the Node.js version via  `.nvmrc` and can select via:
 
 - Node.js 14
 - Node.js 16
 - Node.js 18
 
-If you need to change the version of Node.js for your Front-End Site, you can test the new version by pushing the updated `.nvmrc` to a branch first.
+We recommend switching to the [V1 build pipeline](/guides/decoupled/overview/v1-pipeline) to access higher versions of Node.js and get faster build times.
 
 ### Change Site Name
 
@@ -122,6 +145,43 @@ Adjustments to these settings might be required if you are not using a starter k
 
 ![Build and Output Settings](../../../../images/fes-build-output-settings.png)
 
+## Build Cache
+
+The first build on [any environment](/guides/decoupled/overview/considerations#types-of-environments) runs without a cache. During the first build, Pantheon caches the following assets based on the framework you’ve selected:
+
+*  `.node_modules` (all sites)
+* `.next/cache` (when a site is build using Next.js)
+* `.cache` and `public/` (when a site is built using Gatsby)
+
+Subsequent builds on the same environment will use this cache, unless you have taken steps to bust or purge the cache.
+
+These assets are cached for 365 days or until they are purged.
+
+For sites using Gatsby as a framework, please note that when you publish or edit post, the cache from the previous build will be used, but new and edited content will be included in the final deployment.
+
+### Purging the Build Cache
+
+Pantheon caches assets during the build process based on the project framework. To see more about what is cached and how, please see the Build Cache reference.
+
+During the development and management of a project you might want to run a build with a clean cache. There are several ways to do this.
+
+### Purge the Build Cache in the UI
+
+Each environment in the Pantheon dashboard includes an option to clear cache and build again from the most recent commit. For the live environment:
+
+![Screenshot of trigger  menu](../../../../images/decoupled/cache--live-env-build-without-cache.png)
+
+For a Multidev and Pull Request environments, you can access the same option from the listing in the dashboard:
+
+![Screenshot of Multidev menu](../../../../images/decoupled/cache--multidev.png)
+
+### Bust the Build Cache through Code Changes
+
+In addition to clearing the cache in the Dashboard, the following changes to your project will invalidate the existing build cache for an environment:
+
+* Changes to your `package.json` file
+* Changes to the Node.js version (Which presently only happens through `package.json` changes too)
+
 ## Site Environment Variables
 
 Environment variables are key-value pairs configured outside your source code. This means that each value changes depending on the environment.

source/content/guides/decoupled/overview/10-v1-pipeline.md

@@ -0,0 +1,41 @@
+---
+title: Pantheon Front-End Sites
+subtitle: Opting in to the V1 Pipeline
+description: Build Caching and Node Versions
+tags: [webops, workflow, decoupled]
+contributors: [stevector]
+layout: guide
+showtoc: true
+permalink: docs/guides/decoupled/overview/v1-pipeline
+reviewed: "2023-03-23"
+contenttype: [guide]
+innav: [false]
+categories: [create]
+cms: [decoupled]
+audience: [development]
+product: [decoupled]
+integration: [--]
+---
+
+In the Fall of 2023 Pantheon introduced a new build pipeline for Front End Sites.
+Among under-the-hood-optimizations, like [caching of folders between builds](/guides/decoupled/overview/manage-settings#build-cache), [the new pipeline now uses your `package.json` file](/guides/decoupled/overview/manage-settings#nodejs-version) to select the appropriate version of Node.js for your build and your runtime environments.
+
+Beginning on **November 13th, 2023**, newly created sites will automatically use the new pipeline and cannot opt back to the old pipeline. Sites made prior to that date can opt-in to the new pipeline to take advantage of the new features.
+
+On or around **January 15th, 2024**, all new builds for all previously created sites will use the new pipeline.
+
+## How to Opt-In
+
+We recommend trying the new pipeline with a branch or pull request before switching over all brances and builds.
+
+To switch over a single multidev environment, set an environment variable in your site's dashboard named `FLAG_V1_PIPELINE` to the name of a Multidev branch that you can make next like `multi-v1pipeline`.
+
+![Setting FLAG_V1_PIPELINE in the dashboard](../../../../images/decoupled/v1-flag.png)
+
+To see the improvement in build times, you will need to make at least two pushes to the branch.
+The first push will be a full build, and the second push will be a cached build.
+For our own Docs site, we saw a reduction of many minutes in build time.
+
+If you are satisfied with the results, you can switch over all branches and builds by setting the environment variable to `ANY`. If you wish to test across multiple branches, you can set the environment variable to a comma-separated list of environment names like `multi-v1pipeline, multi-v1pipeline2, pr-123`.
+
+![Multiple commna separated values in FLAG_V1_PIPELINE](../../../../images/decoupled/v1-flag-comma.png)

source/content/partials/decoupled-site-environment-variables.md

@@ -21,13 +21,17 @@ Variable names *cannot* include:
 - Commas
 - Reserved words. Reserved words include:
 
-    - PORT
-    - K_SERVICE
-    - K_REVISION
-    - K_CONFIGURATION
-    - CLOUD_RUN_JOB
-    - CLOUD_RUN_EXECUTION
-    - CLOUD_RUN_TASK_INDEX
-    - CLOUD_RUN_TASK_ATTEMPT
-    - CLOUD_RUN_TASK_COUNT
-    - PANTHEON_*
+    - `PORT`
+    - `K_SERVICE`
+    - `K_REVISION`
+    - `K_CONFIGURATION`
+    - `CLOUD_RUN_JOB`
+    - `CLOUD_RUN_EXECUTION`
+    - `CLOUD_RUN_TASK_INDEX`
+    - `CLOUD_RUN_TASK_ATTEMPT`
+    - `CLOUD_RUN_TASK_COUNT`
+    - `PANTHEON_*`
+
+Pantheon can use environment variables as the mechanism to opt-in to new enhancements like:
+
+- `FLAG_V1_PIPELINE` to opt-in to the [V1 build pipeline](/guides/decoupled/overview/v1-pipeline)