From 648e9c28b14feb907a06ccb2a736e805a1c662e4 Mon Sep 17 00:00:00 2001 From: poli0981 <127664709+poli0981@users.noreply.github.com> Date: Sat, 31 Oct 2026 21:58:38 +0700 Subject: [PATCH] build: the alpha line - RELEASE_LINE stamped into every assembly, release.yml's line-vs-tag rule and Velopack alpha channel, CI on the alpha branch, no wiki for an alpha (D73) (beta.32 PR-1) (#344) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The owner, 2026-10-31: an alpha build where new .NET versions are tried, .NET 11 RC3 / C# 15 first, with an experimental-build warning (owner decisions D73-D76, asked while planning). This is the plumbing on main; it changes nothing in a beta. - RELEASE_LINE (main | alpha), read like VERSION by Directory.Build.props, stamped as the FrameLedger.ReleaseLine assembly metadata; any other value is a build error. Shared.BuildLine reads it back for composition (BuildLineTests, AssemblyIdentityTests). - release.yml: the version gate reads RELEASE_LINE - the alpha line takes vX.Y.Z-alpha.N and nothing else, no other line may carry an -alpha. tag; an alpha's vpk download and pack take --channel alpha (feed releases.alpha.json, asset names from assets..json); the main line's pack command is unchanged. An alpha's release is titled "(experimental alpha)". - ci.yml: also on pushes to alpha; no sonarcloud job and no Changelog step for pull requests into alpha. wiki.yml: no publish after an -alpha. tag. - tools/fps-impact-runbook.ps1: the Agent path no longer names a TFM. - Docs: 12_BUILD §The alpha line, 13_CI_CD §The alpha line (+ ci/release/wiki sections, branch policy), 11_UPDATER §Channels corrected in place (the alpha line uses Velopack channels; GithubSource reads the newest ten releases, hence one alpha per beta), 20_OPEN_QUESTIONS §G "The main line's .NET" with its decision table written first, CLAUDE.md, CHANGELOG. Co-authored-by: Claude Opus 5.5 --- .github/workflows/ci.yml | 13 ++++- .github/workflows/release.yml | 54 +++++++++++++----- .github/workflows/wiki.yml | 5 +- CHANGELOG.md | 11 ++++ CLAUDE.md | 3 +- Directory.Build.props | 17 ++++++ RELEASE_LINE | 1 + docs/11_UPDATER.md | 14 ++++- docs/12_BUILD.md | 43 +++++++++++++- docs/13_CI_CD.md | 36 +++++++++++- docs/20_OPEN_QUESTIONS.md | 1 + src/FrameLedger.Shared/BuildLine.cs | 45 +++++++++++++++ .../AssemblyIdentityTests.cs | 3 + .../BuildLineTests.cs | 57 +++++++++++++++++++ tools/fps-impact-runbook.ps1 | 9 ++- 15 files changed, 288 insertions(+), 24 deletions(-) create mode 100644 RELEASE_LINE create mode 100644 src/FrameLedger.Shared/BuildLine.cs create mode 100644 tests/FrameLedger.Infrastructure.Tests/BuildLineTests.cs 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()) + + + + + + + +