Adopt GitFlow, and document CI and releasing under docs/

.github/workflows/build-skip.yml

@@ -13,10 +13,11 @@
 # success under the same `ubuntu-latest` context — satisfying the rule without paying
 # for a real build.
 #
-# Two things must stay aligned with build.yml, which is generated from
+# Three things must stay aligned with build.yml, which is generated from
 # build/Build.CI.GitHubActions.cs:
 #   - the job name (`ubuntu-latest`), because that IS the status-check context;
-#   - the path set, as the exact complement of that file's OnPullRequestExcludePaths.
+#   - the path set, as the exact complement of that file's OnPullRequestExcludePaths;
+#   - the branch list, as the same set of long-lived branches a PR can target.
 # A PR touching both a .md and a source file runs both workflows; both report the same
 # context and both pass, which is fine.
 
@@ -25,7 +26,9 @@ name: build
 on:
   pull_request:
     branches:
+      - develop
       - main
+      - 'support/*'
     paths:
       - '**/*.md'
 

.github/workflows/build.yml

@@ -19,7 +19,9 @@ name: build
 on:
   pull_request:
     branches:
+      - develop
       - main
+      - 'support/*'
     paths-ignore:
       - '**/*.md'
 

.github/workflows/preview.yml

@@ -1,4 +1,4 @@
-# Hand-written (not auto-generated). The "preview" channel — per-commit builds of main.
+# Hand-written (not auto-generated). The "preview" channel — per-commit builds of develop.
 #
 # Counterpart to the framework repo's publish-packages-preview.yml, which pushes a
 # -preview prerelease to GitHub Packages on every commit to main. The extension can't
@@ -22,13 +22,18 @@
 # The .vsix is marked as a marketplace pre-release, so if it is ever sideloaded next to
 # a stable build VS Code shows it as pre-release rather than silently as a release.
 #
+# See docs/ci.md for how this fits with the other workflows.
+#
 # NOTE: this publishes NOTHING to any marketplace. It is the GitHub pre-stage only.
 name: preview
 
 on:
   push:
     branches:
-      - main
+      # develop is the integration trunk under GitFlow, so it is what "latest" means.
+      # main only ever receives release and hotfix merges, and those are tagged, so a
+      # preview build of main would duplicate a release build of the same commit.
+      - develop
     paths-ignore:
       - '**/*.md'
   workflow_dispatch:
@@ -108,7 +113,7 @@ jobs:
           set -euo pipefail
 
           NOTES=$(cat <<EOF
-          Rolling preview build of \`main\` — **replaced on every push**, so this release is not a
+          Rolling preview build of \`develop\` — **replaced on every push**, so this release is not a
           durable reference. For a fixed version, use a tagged release instead.
 
           | | |

.github/workflows/publish.yml

@@ -65,13 +65,17 @@ jobs:
       - uses: actions/checkout@v7
         with:
           fetch-depth: 0
-      - name: 'Verify tag is reachable from a release branch'
+      - name: 'Verify tag is reachable from a production branch'
         run: |
           set -euo pipefail
+          # Releases come from main (current line) or a support/vX.Y line (older Fallout
+          # line still being served). NOT develop: under GitFlow the trunk is never
+          # tagged for release — it ships through the preview channel instead.
           REACHABLE=$(git branch -r --contains "${{ github.sha }}" \
-            | grep -E 'origin/(main|release/v[0-9]+\.[0-9]+)$' || true)
+            | grep -E 'origin/(main|support/v[0-9]+\.[0-9]+)$' || true)
           if [ -z "$REACHABLE" ]; then
-            echo "::error::Tag ${GITHUB_REF_NAME} is not reachable from main or a release/vX.Y branch."
+            echo "::error::Tag ${GITHUB_REF_NAME} is not reachable from main or a support/vX.Y branch."
+            echo "Release tags are cut from production branches only — see docs/branching-and-release.md."
             exit 1
           fi
           echo "Tag ${GITHUB_REF_NAME} validated. Reachable from:"

.vscodeignore

@@ -18,8 +18,8 @@ nuget.config
 version.json
 build.ps1
 build.sh
-# Maintainer-facing; the marketplace page renders README.md + CHANGELOG.md only.
-RELEASING.md
+# Maintainer-facing; the marketplace page renders README.md only.
+docs/**
 
 # Ship only Mermaid's self-contained UMD bundle (loaded by the graph webview via a
 # classic <script> tag), not its entire dependency tree or the code-split ESM build.

README.md

@@ -18,7 +18,11 @@ Explore, run, and visualize your [Fallout](https://github.com/Fallout-build/Fall
 
 The extension's `major.minor` track the Fallout framework release line it targets — 10.4.x builds against Fallout 10.4 — while the patch moves independently. A mismatch between the extension and the framework your workspace builds with surfaces as a non-blocking warning.
 
-Versions are computed by [Nerdbank.GitVersioning](https://github.com/dotnet/Nerdbank.GitVersioning) from `version.json`, the same as the framework itself; the build fails if the declared line drifts from the Fallout version it actually references. Release candidates are published as GitHub pre-releases only — see [RELEASING.md](RELEASING.md).
+Versions are computed by [Nerdbank.GitVersioning](https://github.com/dotnet/Nerdbank.GitVersioning) from `version.json`, the same as the framework itself; the build fails if the declared line drifts from the Fallout version it actually references. Release candidates are published as GitHub pre-releases only.
+
+## Contributing
+
+This repository uses GitFlow: branch from `develop`, PR back into `develop`. See [docs/branching-and-release.md](docs/branching-and-release.md), [docs/ci.md](docs/ci.md) and [docs/releasing.md](docs/releasing.md).
 
 ## License
 

build/Build.CI.GitHubActions.cs

@@ -28,7 +28,10 @@
     ConcurrencyGroup = "${{ github.workflow }}-${{ github.ref }}",
     ConcurrencyCancelInProgress = true,
     CheckoutRef = "${{ github.head_ref }}",
-    OnPullRequestBranches = [MainBranch],
+    // Every long-lived branch a PR can target (docs/branching-and-release.md): the trunk,
+    // production, and any support line. Feature branches themselves run nothing until a PR
+    // is opened — there is no value in gating work that isn't asking to land yet.
+    OnPullRequestBranches = [DevelopBranch, MainBranch, SupportBranchPattern],
     // Kept to a single pattern so build-skip.yml can express the exact inverse. Anything
     // more clever here (negations, directory carve-outs) makes the two sets drift, and a
     // gap between them means a PR blocked forever on a required check that never fires.
@@ -37,5 +40,12 @@
     PublishArtifacts = false)]
 partial class Build
 {
+    /// <summary>Integration trunk and default branch. All feature work lands here first.</summary>
+    const string DevelopBranch = "develop";
+
+    /// <summary>Production. Only release and hotfix merges land here, and each is tagged.</summary>
     const string MainBranch = "main";
+
+    /// <summary>Long-lived maintenance line for an older Fallout release line, e.g. support/v10.4.</summary>
+    const string SupportBranchPattern = "support/*";
 }