Update docs for new GH Actions Experimental Release workflow (#9083)

.github/workflows/nightly.yml

@@ -49,10 +49,7 @@ jobs:
       - name: 🕵️ Check for changes
         id: version
         run: |
-          # get latest commit sha
-          SHA=$(git rev-parse HEAD)
-          # get first 7 characters of sha
-          SHORT_SHA=${SHA::7}
+          SHORT_SHA=$(git rev-parse --short HEAD)
 
           # get latest nightly tag
           LATEST_NIGHTLY_TAG=$(git tag -l v0.0.0-nightly-\* --sort=-creatordate | head -n 1)

.github/workflows/release-experimental.yml

@@ -1,49 +1,28 @@
-# Experimental releases are handled a bit differently than standard releases.
-# Experimental releases can be branched from anywhere as they are not intended
-# for general use, and all packages will be versioned and published with the
-# same hash for testing.
-#
-# This workflow will run when a GitHub release is created from experimental
-# version tag. Unlike standard releases created via Changesets, only one tag
-# should be created for all packages.
-#
-# To create a release:
-# - Create a new branch for the release: git checkout -b `release-experimental`
-#   - IMPORTANT: You should always create a new branch so that the version
-#     changes don't accidentally get merged into `dev` or `main`. The branch
-#     name must follow the convention of `release-experimental` or
-#     `release-experimental-[feature]`.
-# - Make whatever changes you need and commit them:
-#   - `git add . && git commit "experimental changes!"`
-# - Update version numbers and create a release tag:
-#   - `pnpm run version:experimental`
-# - Push to GitHub:
-#   - `git push origin --follow-tags`
-# - Create a new release for the tag on GitHub to trigger the CI workflow that
-#   will publish the release to npm
+name: 🧪 Experimental Release
 
-name: 🚀 Release (experimental)
 on:
-  push:
-    tags:
-      - "v0.0.0-experimental*"
+  workflow_dispatch:
+    inputs:
+      branch:
+        required: true
 
 concurrency: ${{ github.workflow }}-${{ github.ref }}
 
 env:
   CI: true
 
 jobs:
-  release:
-    name: 🧑‍🔬 Experimental Release
-    if: |
-      github.repository == 'remix-run/remix' &&
-      contains(github.ref, 'experimental')
+  experimental:
+    name: 🧪 Experimental Release
+    if: github.repository == 'remix-run/remix'
     runs-on: ubuntu-latest
     steps:
       - name: ⬇️ Checkout repo
         uses: actions/checkout@v4
         with:
+          ref: ${{ github.event.inputs.branch }}
+          # checkout using a custom token so that we can push later on
+          token: ${{ secrets.NIGHTLY_PAT }}
           fetch-depth: 0
 
       - name: 📦 Setup pnpm
@@ -58,6 +37,16 @@ jobs:
       - name: 📥 Install deps
         run: pnpm install --frozen-lockfile
 
+      - name: ⤴️ Update version
+        run: |
+          git config --local user.email "hello@remix.run"
+          git config --local user.name "Remix Run Bot"
+          SHORT_SHA=$(git rev-parse --short HEAD)
+          NEXT_VERSION=0.0.0-experimental-${SHORT_SHA}
+          git checkout -b experimental/${NEXT_VERSION}
+          pnpm run version ${NEXT_VERSION} --skip-prompt
+          git push origin --tags
+
       - name: 🏗 Build
         run: pnpm build
 

DEVELOPMENT.md

@@ -21,12 +21,17 @@ pnpm install
 # run the build
 pnpm build
 
-# run the tests
-pnpm test
-# run the tests for a specific package
-pnpm test react
-# run the tests in watch mode
-pnpm test react --watch
+# run the unit tests
+pnpm test:primary
+
+# run the unit tests for a specific package in watch mode
+pnpm test:primary packages/remix-react --watch
+
+# run the playwright integration tests in Chromium
+pnpm test:integration --project chromium
+
+# run specific playwright integration tests in Chromium
+pnpm test:integration integration/client-data --project chromium
 ```
 
 ## Releases
@@ -40,7 +45,6 @@ New releases should be created from release branches originating from the `dev`
 - Create a new release branch with the `release-` prefix
   - `git checkout -b release-next`
   - **IMPORTANT:** The `release-` prefix is important, as this is what triggers our GitHub CI workflow that will ultimately publish the release
-  - Branches named `release-experimental` will not trigger our release workflow, as experimental releases handled differently (outlined below)
 - Merge `main` into the release branch
 
 Changesets will do most of the heavy lifting for our releases. When changes are made to the codebase, an accompanying changeset file should be included to document the change. Those files will dictate how Changesets will version our packages and what shows up in the changelogs.
@@ -100,14 +104,19 @@ Hotfix releases follow the same process as standard releases above, but the `rel
 
 ### Experimental releases
 
-Experimental releases do not need to be branched off of `dev`. Experimental releases can be branched from anywhere as they are not intended for general use.
+Experimental releases use a [manually-triggered Github Actions workflow](./.github/workflows/release-experimental.yml) and can be built from any existing branch. to build and publish an experimental release:
+
+- Commit your changes to a branch
+- Push the branch to github
+- Go to the Github Actions UI for the [release-experimental.yml workflow](https://github.com/remix-run/remix/actions/workflows/release-experimental-dispatch.yml)
+- Click the `Run workflow` dropdown
+- Leave the `Use workflow from` dropdown as `main`
+- Enter your feature branch in the `branch` input
+- Click the `Run workflow` button
+
+### Nightly releases
 
-- Create a new branch for the release: `git checkout -b release-experimental`
-- Make whatever changes you need and commit them: `git add . && git commit "experimental changes!"`
-- Update version numbers and create a release tag: `pnpm version:experimental`
-- Push to GitHub: `git push origin --follow-tags`
-- Create a new release for the tag on GitHub to trigger the CI workflow that will publish the release to npm
-  - Make sure you check the "prerelease" checkbox so it is not mistaken for a stable release
+Nightly releases happen automatically at midnight PST via a [cron-driven workflow](./.github/workflows/nightly.yml) that is essentially the same as the experimental releases, but also performs some validations after the release.
 
 ## Local Development Tips and Tricks
 
@@ -138,83 +147,3 @@ LOCAL_BUILD_DIRECTORY=../my-remix-app pnpm watch
 ```
 
 Now - any time you make changes in the Remix repository, they will be written out to the appropriate locations in `../my-remix-app/node_modules` and you can restart the `npm run dev` command to pick them up 🎉.
-
-### Transition Manager Flows
-
-The transition manager is a complex and heavily async bit of logic that is foundational to Remix's ability to manage data loading, submission, error handling, and interruptions. Due to the user-driven nature of interruptions we don't quite believe it can be modeled as a finite state machine, however we have modeled some of the happy path flows below for clarity.
-
-#### Transitions
-
-_Note: This does not depict error or interruption flows_
-
-```mermaid
-graph LR
-  %% <Link> transition
-  idle -->|link clicked| loading/normalLoad
-  idle -->|form method=get| submitting/loaderSubmission
-  idle -->|form method=post| submitting/actionSubmission
-  idle -->|fetcher action redirects| loading/fetchActionRedirect
-
-  subgraph "&lt;Link&gt; transition"
-  loading/normalLoad -->|loader redirected| loading/normalRedirect
-  loading/normalRedirect --> loading/normalRedirect
-  end
-  loading/normalLoad -->|loaders completed| idle
-  loading/normalRedirect -->|loaders completed| idle
-
-  subgraph "&lt;Form method=get&gt;"
-  submitting/loaderSubmission -->|loader redirected| loading/loaderSubmissionRedirect
-  loading/loaderSubmissionRedirect --> loading/loaderSubmissionRedirect
-  end
-  submitting/loaderSubmission -->|loaders completed| idle
-  loading/loaderSubmissionRedirect -->|loaders completed| idle
-
-  subgraph "&lt;Form method=post&gt;"
-  submitting/actionSubmission -->|action returned| loading/actionReload
-  submitting/actionSubmission -->|action redirected| loading/actionRedirect
-  loading/actionReload -->|loader redirected| loading/actionRedirect
-  loading/actionRedirect --> loading/actionRedirect
-  end
-  loading/actionReload -->|loaders completed| idle
-  loading/actionRedirect -->|loaders completed| idle
-
-  subgraph "Fetcher action redirect"
-  loading/fetchActionRedirect --> loading/fetchActionRedirect
-  end
-  loading/fetchActionRedirect -->|loaders completed| idle
-```
-
-#### Fetchers
-
-_Note: This does not depict error or interruption flows, nor the ability to re-use fetchers once they've reached `idle/done`._
-
-```mermaid
-graph LR
-  idle/init -->|"load"| loading/normalLoad
-  idle/init -->|"submit (get)"| submitting/loaderSubmission
-  idle/init -->|"submit (post)"| submitting/actionSubmission
-
-  subgraph "Normal Fetch"
-  loading/normalLoad -.->|loader redirected| T1{{transition}}
-  end
-  loading/normalLoad -->|loader completed| idle/done
-  T1{{transition}} -.-> idle/done
-
-  subgraph "Loader Submission"
-  submitting/loaderSubmission -.->|"loader redirected"| T2{{transition}}
-  end
-  submitting/loaderSubmission -->|loader completed| idle/done
-  T2{{transition}} -.-> idle/done
-
-  subgraph "Action Submission"
-  submitting/actionSubmission -->|action completed| loading/actionReload
-  submitting/actionSubmission -->|action redirected| loading/actionRedirect
-  loading/actionRedirect -.-> T3{{transition}}
-  loading/actionReload -.-> |loaders redirected| T3{{transition}}
-  end
-  T3{{transition}} -.-> idle/done
-  loading/actionReload --> |loaders completed| idle/done
-
-  classDef transition fill:lightgreen;
-  class T1,T2,T3 transition;
-```

package.json

@@ -31,7 +31,6 @@
     "changeset:version": "changeset version && node ./scripts/remove-prerelease-changelogs.mjs && node ./scripts/patchup-version.mjs",
     "changeset:release": "pnpm build --tsc && changeset publish",
     "version": "node ./scripts/version.js",
-    "version:experimental": "node ./scripts/version.js experimental",
     "watch": "rollup -c --watch --watch.onEnd=\"node scripts/copy-build-to-dist.mjs\""
   },
   "packageManager": "pnpm@8.10.5",

scripts/utils.js

@@ -191,20 +191,14 @@ const updateDenoImportMap = async (importMapPath, nextVersion) => {
 /**
  * @param {string} nextVersion
  */
-async function incrementRemixVersion(nextVersion, syncLockFile = false) {
+async function incrementRemixVersion(nextVersion) {
   // Update version numbers in package.json for all packages
   await updateRemixVersion("remix", nextVersion);
   await updateRemixVersion("create-remix", nextVersion);
   for (let name of remixPackages.all) {
     await updateRemixVersion(`remix-${name}`, nextVersion);
   }
 
-  // Sync up the pnpm-lock.yaml file with the new experimental version
-  if (syncLockFile) {
-    console.log(chalk.green("  Syncing pnpm lockfile..."));
-    execSync("pnpm install --no-frozen-lockfile");
-  }
-
   // Update version numbers in Deno's import maps
   await Promise.all(
     [

scripts/version.js

@@ -42,7 +42,7 @@ async function run(args) {
     if (answer === false) return 0;
   }
 
-  await incrementRemixVersion(nextVersion, givenVersion === "experimental");
+  await incrementRemixVersion(nextVersion);
 }
 
 /**
@@ -57,15 +57,7 @@ function getNextVersion(currentVersion, givenVersion, prereleaseId = "pre") {
     process.exit(1);
   }
 
-  let nextVersion;
-  if (givenVersion === "experimental") {
-    let hash = execSync(`git rev-parse --short HEAD`).toString().trim();
-    nextVersion = `0.0.0-experimental-${hash}`;
-  } else {
-    // @ts-ignore
-    nextVersion = semver.inc(currentVersion, givenVersion, prereleaseId);
-  }
-
+  let nextVersion = semver.inc(currentVersion, givenVersion, prereleaseId);
   if (nextVersion == null) {
     console.error(`Invalid version specifier: ${givenVersion}`);
     process.exit(1);