diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 337ae875..27e0a044 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -20,7 +20,9 @@ name: CI
on:
push:
- branches: [main]
+ # `alpha` since 2026-10-31 (D73, docs/13_CI_CD.md §The alpha line): the same source on a prerelease .NET, whose
+ # merges and syncs from main need the same gate under its own global.json.
+ branches: [main, alpha]
pull_request:
workflow_dispatch:
@@ -176,8 +178,11 @@ jobs:
Write-Host ("vulkaninfo.exe on PATH: {0}" -f ($(if ($cmd) { $cmd.Source } else { 'no' })))
Write-Host ("HKLM:\SOFTWARE\Khronos\Vulkan\Drivers present: {0}" -f (Test-Path 'HKLM:\SOFTWARE\Khronos\Vulkan\Drivers'))
+ # Not for a pull request into `alpha` (D73): what the alpha line changes is written in its release's own file on
+ # main (docs/changelog/x.y.z-alpha.N.md), and an [Unreleased] entry on the alpha branch would collide with main's
+ # at every sync.
- name: Changelog
- if: github.event_name == 'pull_request'
+ if: github.event_name == 'pull_request' && github.base_ref != 'alpha'
shell: pwsh
env:
GH_TOKEN: ${{ github.token }}
@@ -221,9 +226,11 @@ jobs:
# it. Any other branch is refused by the organisation's plan - "Organization
# is not allowed to access data from non main branches", measured on a
# workflow_dispatch run of a feature branch, 2026-10-25 - so a dispatch on
- # one runs `check` alone.
+ # one runs `check` alone. The same plan is why a pull request INTO `alpha`
+ # (D73) and a push to it run `check` alone: SonarCloud analyses main's line.
if: >-
(github.event_name == 'pull_request' &&
+ github.base_ref != 'alpha' &&
github.event.pull_request.head.repo.full_name == github.repository &&
github.event.pull_request.user.login != 'dependabot[bot]') ||
(github.event_name != 'pull_request' && github.ref == 'refs/heads/main')
diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
index c07d66f5..284bd268 100644
--- a/.github/workflows/release.yml
+++ b/.github/workflows/release.yml
@@ -22,6 +22,13 @@
# -p:Version; the native blocks keep the numeric core (CMake's project() accepts
# nothing else).
#
+# THE ALPHA LINE (2026-10-31, owner decisions D73-D76; 12_BUILD §The alpha line): the
+# RELEASE_LINE file says `alpha` on the long-lived `alpha` branch, where the same source
+# builds on a prerelease .NET. Its tags are `vX.Y.Z-alpha.N` and nothing else, no other
+# line may carry one, and its packages go to Velopack's `alpha` channel
+# (releases.alpha.json) - which no beta reads, as no alpha reads releases.win.json
+# (11_UPDATER §Channels). The version gate below enforces all three.
+#
# A DRY RUN (2026-09-16, P5 prep): `workflow_dispatch` with a version runs every
# step below — the gate, the publish, the tree assertion, vpk, the checksums — and
# uploads the result as a workflow artifact, but creates no tag and no Release.
@@ -101,6 +108,14 @@ jobs:
$pre = if ($m.Groups[2].Success) { 'true' } else { 'false' }
$file = (Get-Content VERSION -Raw).Trim()
if ($core -ne $file) { throw "tag $tag has numeric core $core but VERSION says $file — bump VERSION in the same commit as the changelog section, then tag" }
+ # D73: the release line this commit builds (Directory.Build.props refuses any other value too) and the tags it may
+ # carry - an alpha's on the alpha line only, and nothing else there.
+ $line = (Get-Content RELEASE_LINE -Raw).Trim()
+ if ($line -cnotin @('main', 'alpha')) { throw "RELEASE_LINE says '$line'; it must be main or alpha" }
+ $suffix = $m.Groups[2].Value
+ if ($line -eq 'alpha' -and $suffix -cnotmatch '^-alpha\.\d+$') { throw "this commit is on the alpha line (RELEASE_LINE); its tag must be vX.Y.Z-alpha.N, not $tag" }
+ if ($line -ne 'alpha' -and $suffix -match 'alpha') { throw "tag $tag names an alpha, but RELEASE_LINE says '$line': an alpha is tagged on the alpha branch, nowhere else" }
+ $channel = if ($line -eq 'alpha') { 'alpha' } else { 'win' }
New-Item -ItemType Directory -Force out | Out-Null
./tools/release-notes.ps1 -Version $full -OutFile out/notes.md
if ($LASTEXITCODE -ne 0) {
@@ -113,8 +128,9 @@ jobs:
}
"version=$full" >> $env:GITHUB_OUTPUT
"prerelease=$pre" >> $env:GITHUB_OUTPUT
+ "channel=$channel" >> $env:GITHUB_OUTPUT
"dry_run=$($dry.ToString().ToLowerInvariant())" >> $env:GITHUB_OUTPUT
- Write-Host "$(if ($dry) { 'DRY RUN of' } else { 'releasing' }) $full (pre-release: $pre)"
+ Write-Host "$(if ($dry) { 'DRY RUN of' } else { 'releasing' }) $full (pre-release: $pre; line: $line; Velopack channel: $channel)"
# The Overlay's build id is `git describe --dirty` at CMake's configure
# (src/native/FrameLedger.Shm/CMakeLists.txt), and the next step edits tracked
@@ -247,32 +263,42 @@ jobs:
dotnet tool install -g vpk --version 1.2.161
if ($LASTEXITCODE -ne 0) { throw 'vpk install failed' }
$v = '${{ steps.version.outputs.version }}'
+ # D73: `win` (Velopack's default on Windows) for the main line, `alpha` for the alpha line - each release's feed
+ # and the previous release its delta is made from are its own line's. The main line's pack keeps its exact
+ # command (no --channel), so a beta is packed as every beta before the alpha line existed.
+ $channel = '${{ steps.version.outputs.channel }}'
New-Item -ItemType Directory out/release -Force | Out-Null
- vpk download github --repoUrl "https://github.com/${{ github.repository }}" --channel win --pre --token $env:GH_TOKEN --outputDir out/release
+ vpk download github --repoUrl "https://github.com/${{ github.repository }}" --channel $channel --pre --token $env:GH_TOKEN --outputDir out/release
if ($LASTEXITCODE -ne 0) { Write-Host '::warning::the previous release could not be downloaded - this release carries a full package only' }
Write-Host 'previous release:'
Get-ChildItem out/release -File | ForEach-Object { Write-Host (" {0,-48} {1,12:N0}" -f $_.Name, $_.Length) }
- vpk pack --packId FrameLedger.App --packVersion $v --packDir out/app --mainExe FrameLedger.exe --packTitle FrameLedger --packAuthors FrameLedger --releaseNotes out/notes.md --outputDir out/release
+ $pack = @('pack', '--packId', 'FrameLedger.App', '--packVersion', $v, '--packDir', 'out/app', '--mainExe', 'FrameLedger.exe', '--packTitle', 'FrameLedger', '--packAuthors', 'FrameLedger', '--releaseNotes', 'out/notes.md', '--outputDir', 'out/release')
+ if ($channel -ne 'win') { $pack += @('--channel', $channel) }
+ vpk @pack
if ($LASTEXITCODE -ne 0) { throw 'vpk pack failed' }
- $built = @((Get-Content out/release/assets.win.json -Raw | ConvertFrom-Json) | ForEach-Object { $_.RelativeFileName })
- if ($built.Count -eq 0) { throw 'vpk pack wrote no assets.win.json entries' }
- $keep = $built + @('releases.win.json', 'assets.win.json', 'RELEASES')
+ $assets = "assets.$channel.json"
+ $index = "releases.$channel.json"
+ $legacyName = if ($channel -eq 'win') { 'RELEASES' } else { "RELEASES-$channel" }
+ $built = @((Get-Content "out/release/$assets" -Raw | ConvertFrom-Json) | ForEach-Object { $_.RelativeFileName })
+ if ($built.Count -eq 0) { throw "vpk pack wrote no $assets entries" }
+ $keep = $built + @($index, $assets, $legacyName)
New-Item -ItemType Directory out/previous -Force | Out-Null
Get-ChildItem out/release -File | Where-Object { $keep -notcontains $_.Name } | Move-Item -Destination out/previous
- $feed = Get-Content out/release/releases.win.json -Raw | ConvertFrom-Json
+ $feed = Get-Content "out/release/$index" -Raw | ConvertFrom-Json
$feed.Assets = @($feed.Assets | Where-Object { $built -contains $_.FileName })
if ($feed.Assets.Count -eq 0) { throw 'the feed lists none of this build''s packages' }
- [System.IO.File]::WriteAllText((Join-Path $PWD 'out/release/releases.win.json'), ($feed | ConvertTo-Json -Depth 8 -Compress), [System.Text.UTF8Encoding]::new($false))
- if (Test-Path out/release/RELEASES) {
- $legacy = @(Get-Content out/release/RELEASES | Where-Object { $built -contains ($_ -split ' ')[1] })
- [System.IO.File]::WriteAllLines((Join-Path $PWD 'out/release/RELEASES'), [string[]]$legacy, [System.Text.UTF8Encoding]::new($false))
+ [System.IO.File]::WriteAllText((Join-Path $PWD "out/release/$index"), ($feed | ConvertTo-Json -Depth 8 -Compress), [System.Text.UTF8Encoding]::new($false))
+ if (Test-Path "out/release/$legacyName") {
+ $legacy = @(Get-Content "out/release/$legacyName" | Where-Object { $built -contains ($_ -split ' ')[1] })
+ [System.IO.File]::WriteAllLines((Join-Path $PWD "out/release/$legacyName"), [string[]]$legacy, [System.Text.UTF8Encoding]::new($false))
}
Write-Host 'this release:'
Get-ChildItem out/release | ForEach-Object { Write-Host (" {0,-48} {1,12:N0}" -f $_.Name, $_.Length) }
Write-Host ('feed: ' + (($feed.Assets | ForEach-Object { '{0} {1} {2}' -f $_.Type, $_.Version, $_.FileName }) -join '; '))
- if (-not (Test-Path out/release/FrameLedger.App-win-Setup.exe)) { throw 'vpk did not produce FrameLedger.App-win-Setup.exe (README §Install names it)' }
+ $setup = "FrameLedger.App-$channel-Setup.exe"
+ if (-not (Test-Path "out/release/$setup")) { throw "vpk did not produce $setup (README §Install names the beta's, guide/11-alpha-builds.md the alpha's)" }
$delta = "out/release/FrameLedger.App-$v-delta.nupkg"
if (Get-ChildItem out/previous -Filter '*-full.nupkg' -ErrorAction SilentlyContinue) {
if (-not (Test-Path $delta)) { throw "the previous full package was downloaded, but vpk produced no delta ($delta)" }
@@ -301,7 +327,9 @@ jobs:
run: |
$ErrorActionPreference = 'Stop'
$v = '${{ steps.version.outputs.version }}'
- $ghArgs = @('release', 'create', $env:GITHUB_REF_NAME, '--title', "FrameLedger $v", '--notes-file', 'out/notes.md', '--verify-tag')
+ # An alpha says what it is in the list of releases too, not only in its notes (D74).
+ $title = if ('${{ steps.version.outputs.channel }}' -eq 'alpha') { "FrameLedger $v (experimental alpha)" } else { "FrameLedger $v" }
+ $ghArgs = @('release', 'create', $env:GITHUB_REF_NAME, '--title', $title, '--notes-file', 'out/notes.md', '--verify-tag')
if ('${{ steps.version.outputs.prerelease }}' -eq 'true') { $ghArgs += '--prerelease' }
$ghArgs += Get-ChildItem out/release -File | ForEach-Object { $_.FullName }
gh @ghArgs
diff --git a/.github/workflows/wiki.yml b/.github/workflows/wiki.yml
index 29e677e8..3c7f19dc 100644
--- a/.github/workflows/wiki.yml
+++ b/.github/workflows/wiki.yml
@@ -44,12 +44,15 @@ jobs:
# that succeeded - in THIS repository. A fork cannot start this repository's Release run (it runs on a tag push or by
# hand), so the head checked out below is always the owner's; the repository check says so in the condition rather
# than leaving it to release.yml's triggers (SonarCloud githubactions:S7631, beta.26).
+ # Nor does an alpha's release (D73, 2026-10-31): the wiki shows the newest beta, and an alpha's tag is on the `alpha`
+ # branch, whose guide is the beta's it was cut from - publishing it would only move the wiki's links off main's line.
if: >-
github.event_name == 'workflow_dispatch' ||
(github.event.workflow_run.conclusion == 'success' &&
github.event.workflow_run.event == 'push' &&
github.event.workflow_run.head_repository.full_name == github.repository &&
- startsWith(github.event.workflow_run.head_branch, 'v'))
+ startsWith(github.event.workflow_run.head_branch, 'v') &&
+ !contains(github.event.workflow_run.head_branch, '-alpha.'))
runs-on: windows-latest
timeout-minutes: 10
env:
diff --git a/CHANGELOG.md b/CHANGELOG.md
index cbafeda9..f03dd00b 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -35,6 +35,17 @@ numeric core and does not move; the heading is the full version — corrected 20
## [Unreleased]
+### Added
+
+- **The alpha line** (the owner's request of 2026-10-31, owner decisions D73–D76): an `alpha` branch builds this source
+ on a prerelease .NET — .NET 11 RC3 first — and publishes it as `x.y.z-alpha.N` pre-releases on an update channel of
+ their own, so a beta never updates to an alpha and an alpha never to a beta. What the line needs on main changes nothing
+ in a beta: the `RELEASE_LINE` file and the line every assembly is stamped with (`Shared.BuildLine`), `release.yml`'s
+ rule that an alpha is tagged on the alpha line and nowhere else and packed on Velopack's `alpha` channel, CI on the
+ `alpha` branch, and no wiki publish for an alpha (`docs/12_BUILD.md` §The alpha line, `docs/13_CI_CD.md` §The alpha
+ line, `docs/11_UPDATER.md` §Channels). Whether the main line ever leaves .NET 10 is an open question whose decision
+ table is written before the evidence (`docs/20_OPEN_QUESTIONS.md` §G, *The main line's .NET*).
+
## Releases
Newest first. Each file holds that release's section exactly as it stood here.
diff --git a/CLAUDE.md b/CLAUDE.md
index 643ac49e..856b6c4d 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -42,7 +42,7 @@ A C++ DLL (`FrameLedger.Overlay.dll`) is injected into games the user explicitly
| Concern | Choice |
|---|---|
-| Managed runtime | .NET 10 (LTS, pinned via `global.json`), C# 14, TFM `net10.0-windows10.0.22621.0` with `SupportedOSPlatformVersion=10.0.19045.0` (Win10 22H2 floor, NFR-8), x64 only — `docs/12_BUILD.md` |
+| Managed runtime | .NET 10 (LTS, pinned via `global.json`), C# 14, TFM `net10.0-windows10.0.22621.0` with `SupportedOSPlatformVersion=10.0.19045.0` (Win10 22H2 floor, NFR-8), x64 only — `docs/12_BUILD.md`. **The `alpha` branch** (D73–D76, 2026-10-31) builds the same source on a prerelease .NET — .NET 11 RC3, C# 15 — and differs from main only where `docs/12_BUILD.md` §The alpha line lists; code on main must keep compiling as C# 14 on .NET 10, so no C# 15 syntax |
| Native | **C++20, MSVC v143+, `/MT` static CRT, `/GS`, `/guard:cf`, no RTTI, no C++ exceptions in hook paths** |
| Hooking | **MinHook** (BSD-2-Clause) for inline hooks; direct vtable-entry swap for COM interfaces |
| Vulkan | **Implicit Vulkan layer** (`VK_LAYER_FRAMELEDGER_overlay`), not hooking — `17_HOOK_ENGINE` §Vulkan |
@@ -68,6 +68,7 @@ FrameLedger.slnx # XML solution format (SDK default since .NET 10)
NOTICE # copyright + the GPLv3 section 7 additional terms (beta.12, D45)
CONTRIBUTING.md FORKING.md CODE_OF_CONDUCT.md # for people who build, contribute or redistribute
global.json # pins the SDK band — see 12_BUILD
+RELEASE_LINE # `main`, or `alpha` on the alpha branch (D73, 2026-10-31) — 12_BUILD §The alpha line
build.ps1 # the quality gate; CI runs this identical script
SonarQube.Analysis.xml # SonarCloud's settings for ci.yml's sonarcloud job (D68, 2026-10-25; it replaced
.config/dotnet-tools.json # .sonarcloud.properties) and the scanner it runs — 13_CI_CD §SonarCloud
diff --git a/Directory.Build.props b/Directory.Build.props
index 9ce6a003..a81496c8 100644
--- a/Directory.Build.props
+++ b/Directory.Build.props
@@ -67,8 +67,25 @@
$(MSBuildThisFileDirectory)VERSION
$([System.IO.File]::ReadAllText('$(FrameLedgerVersionFile)').Trim())
false
+
+
+ $(MSBuildThisFileDirectory)RELEASE_LINE
+ $([System.IO.File]::ReadAllText('$(FrameLedgerReleaseLineFile)').Trim())
+
+
+
+
+
+
+
+