Version Management for release 0.5 and Beyond

.editorconfig

@@ -14,6 +14,10 @@ end_of_line = lf
 insert_final_newline = true
 trim_trailing_whitespace = true
 
+[*.rc]
+# rc.exe assumes the system ANSI codepage without a BOM, which would mangle non-ASCII strings like the copyright symbol.
+charset = utf-8-bom
+
 [.gitattributes]
 charset = utf-8
 end_of_line = unset

.github/actions/build-phobos/action.yml

@@ -8,6 +8,10 @@ inputs:
   build-config:
     description: 'Configuration to build'
     required: true
+  build-type:
+    description: 'Build type: NIGHTLY or RELEASE'
+    required: true
+    default: 'NIGHTLY'
   syringeex-tag:
     description: 'SyringeEx release tag to bundle (empty for the latest release)'
     required: false
@@ -26,7 +30,7 @@ runs:
     working-directory: ${{env.GITHUB_WORKSPACE}}
     # Add additional options to the MSBuild command line here (like platform or verbosity level).
     # See https://docs.microsoft.com/visualstudio/msbuild/msbuild-command-line-reference
-    run: msbuild /m /p:Configuration=${{inputs.build-config}} /p:GitCommit=${{github.sha}} /p:GitBranch=${{github.ref}} ${{inputs.sln-path}}
+    run: msbuild /m /p:Configuration=${{inputs.build-config}} /p:BuildType=${{inputs.build-type}} ${{inputs.sln-path}}
     shell: cmd
 
   - name: Stage exception database

.github/copilot-instructions.md

@@ -23,17 +23,18 @@ git submodule update --init --recursive
 | Config | Command | Output |
 |--------|---------|--------|
 | Debug (recommended for dev) | `scripts\build_debug.bat` | `Debug\Phobos.dll` + `.pdb` |
-| DevBuild (CI nightly) | `scripts\build_devbuild.bat` | `DevBuild\Phobos.dll` + `.pdb` |
 | Release | `scripts\build_release.bat` | `Release\Phobos.dll` + `.pdb` |
 
+There are only two build configurations, `Debug` and `Release`. What kind of build is produced (nightly or stable release) is a separate axis, set by the `BuildType` MSBuild property (`NIGHTLY` or `RELEASE`), which defines the preprocessor macro of the same name; an unset `BuildType` means a plain local build. A pre-release is a `RELEASE` build whose `PRERELEASE_SUFFIX` (hardcoded in `src/Phobos.version.h`) is still defined; remove the suffix there to build a stable release.
+
 These scripts invoke `scripts\run_msbuild.bat`, which locates the VS Developer Command Prompt via `vswhere.exe` (bundled in `scripts/`), then runs `msbuild`. **VS 2022 or VS Build Tools 2022** with the components listed in `.vsconfig` must be installed:
 - `Microsoft.VisualStudio.Component.VC.Tools.x86.x64`
 - `Microsoft.VisualStudio.Component.Windows10SDK.20348`
 - `Microsoft.VisualStudio.Component.VC.ATL`
 
-**In VS Code**, prefer the pre-configured build tasks over running scripts directly unless there are issues. The workspace defines a **"Build Phobos"** task (default build task) that prompts for Debug/DevBuild/Release. Run it via `Ctrl+Shift+B` or the `Tasks: Run Build Task` command. A **"Cleanup build folders"** task is also available.
+**In VS Code**, prefer the pre-configured build tasks over running scripts directly unless there are issues. The workspace defines a **"Build Phobos"** task (default build task) that prompts for Debug/Release. Run it via `Ctrl+Shift+B` or the `Tasks: Run Build Task` command. A **"Cleanup build folders"** task is also available.
 
-**In Visual Studio 2022**, most contributors build directly from the IDE using `Build > Build Solution` (`Ctrl+Shift+B`) with the solution configuration dropdown (Debug/DevBuild/Release). The batch scripts are not needed when building from VS.
+**In Visual Studio 2022**, most contributors build directly from the IDE using `Build > Build Solution` (`Ctrl+Shift+B`) with the solution configuration dropdown (Debug/Release). The batch scripts are not needed when building from VS.
 
 The build takes roughly 1–3 minutes for a full rebuild. Incremental builds are much faster. To clean:
 ```
@@ -42,19 +43,17 @@ scripts\clean.bat
 
 ### CI build (GitHub Actions)
 
-The CI workflow (`.github/actions/build-phobos/action.yml`) builds the **DevBuild** config with MSBuild, passing `/p:GitCommit=<sha> /p:GitBranch=<ref>` for version stamping. The agent should replicate the CI as:
+The release workflow (`.github/workflows/release.yml`) builds the **Release** config with MSBuild, passing `/p:BuildType=RELEASE`; whether that build is a pre-release is decided by `PRERELEASE_SUFFIX` in `src/Phobos.version.h`, not by the workflow. Nightly builds (`.github/workflows/nightly.yml` and the PR nightly) pass `/p:BuildType=NIGHTLY`. Git commit/ref info is not passed from CI in either case: `Phobos.props` runs a `ComputeGitInfo` target that derives the short commit SHA, the ref (e.g. `refs/heads/develop`) and a dirty marker straight from the repository, so local builds are stamped identically. The agent should replicate a nightly CI build as:
 ```
-msbuild /m /p:Configuration=DevBuild Phobos.sln
+msbuild /m /p:Configuration=Release /p:BuildType=NIGHTLY Phobos.sln
 ```
 
 ## Tests & Validation
 
 There is **no automated test suite**. Validation is:
 1. **Successful compilation** with zero errors (warning level 4, but not treated as errors).
-2. **PR CI checks** - the `Pull Request Nightly Build` workflow must pass (builds DevBuild config).
-3. **PR doc checker** (`.github/workflows/pr-doc-checker.yml`) - unless the PR has the `No Documentation Needed` label, these files must be modified:
-   - `docs/Whats-New.md` (changelog entry)
-   - `CREDITS.md` (credit entry; skipped if the `Bugfix` label is set)
+2. **PR CI checks** - the `Pull Request Nightly Build` workflow must pass (builds the Release config as a nightly).
+3. **PR doc checker** (`.github/workflows/pr-doc-checker.yml`) - its three checks (changelog, credits, docs) each pass when the corresponding file is modified, and are skipped individually when the matching label is applied (`Skip Changelog`, `Skip Docs`, `Skip Credits`). Labels are applied by maintainers; see the table in `docs/Contributing.md` for what each kind of change is expected to cover.
 
 Always verify your changes compile by running `scripts\build_debug.bat` before committing.
 
@@ -373,6 +372,8 @@ scripts\build_docs.bat
 
 Output goes to `docs/_build/html/`. Pull requests are automatically built and served by Read the Docs - check the PR status checks for a preview link.
 
+**Local extension `docs/_ext/`**: a small local Sphinx extension (`sanitize_system_messages`, registered as `_ext.sanitize_system_messages` in `docs/conf.py`) strips docutils `system_message` nodes and repairs the `rawsource` that Sphinx's `ApplySourceWorkaround` pollutes with them. Without it, the "Duplicate implicit target name" warnings caused by repeated sub-headings (e.g. the many `#### Vanilla fixes:` blocks inside `{dropdown}`s in `Whats-New.md`) leak into the gettext `.pot`/`.po` files as bogus translatable strings. Do not remove it or drop `sys.path.insert(0, os.path.abspath('.'))` from `conf.py` - the extension is only importable because of that path insert. A standalone reproduction of the underlying Sphinx/MyST bug is in this [gist](https://gist.github.com/Metadorius/ee435861903ba132cd70563c2bdffec1).
+
 ### Translations
 
 The project uses Sphinx internationalization with `.po` files. Currently only **zh_CN** (Chinese) is maintained. The translation workflow:
@@ -401,12 +402,12 @@ Many contributors are non-native English speakers, so the existing documentation
 
 ## PR Checklist
 
-For non-trivial changes (unless labeled `No Documentation Needed`):
+For non-trivial changes:
 1. Update `docs/Whats-New.md` with a changelog entry.
 2. Update `CREDITS.md` with your contribution.
 3. Update relevant documentation pages in `docs/`.
 
-Use `[Minor]` in the PR title for small changes that don't need documentation updates.
+If one of these doesn't apply to your change, ask a maintainer to apply the matching label (`Skip Changelog`, `Skip Docs` or `Skip Credits`) so the corresponding check is skipped. See the table in `docs/Contributing.md` for what each kind of change is expected to cover.
 
 ## Trust These Instructions
 

.github/pull_request_template.md

@@ -1,2 +1,17 @@
-<!-- Please manually add a label named [No Documentation Needed] if this change should not be mentioned in documentation, what's new and no credit needs to be given.
-If the changes are solely made to the documentation, please set the target branch to the pull request named "Weekly Regular Documentation Revisions", rather than the repository's existing branches. -->
+<!--
+If the changes are solely made to the documentation, please set the target branch to the pull request named "Weekly Regular Documentation Revisions", rather than the repository's existing branches.
+-->
+
+## What kind of change is this?
+
+<!-- Tick the row that matches your change. It tells the maintainers which of the changelog, docs and credits checks should run, and which `Skip` labels to apply for the ones that don't. -->
+
+- [ ] **New feature, vanilla bugfix or enhancement of a released feature** - changelog, docs and credits entries are needed.
+- [ ] **Improvement to a new (unreleased) feature** - docs and credits entries are needed; no changelog entry (`Skip Changelog`).
+- [ ] **Bugfix to a new (unreleased) feature** - credits entry is needed; no changelog or docs entries (`Skip Changelog`, `Skip Docs`).
+- [ ] **Bugfix to an old (released) feature** - changelog and credits entries are needed; no docs entry (`Skip Docs`).
+- [ ] **Completely minor change (e.g. a typo fix)** - no entries are needed (`Skip Changelog`, `Skip Docs`, `Skip Credits`).
+
+## Description
+
+<!-- Write your description below. Usually this is your improvement documentation copy, but you may add extra notes or sections or whatever you feel is important for reviewing. -->

.github/workflows/nightly.yml

@@ -3,8 +3,6 @@ name: Nightly Build
 on:
   push:
     branches:
-    - master
-    - main
     - develop
 
 env:
@@ -14,9 +12,7 @@ env:
   # Configuration type to build.
   # You can convert this to a build matrix if you need coverage of multiple configuration types.
   # https://docs.github.com/actions/learn-github-actions/managing-complex-workflows#using-a-build-matrix
-  BUILD_CONFIGURATION: DevBuild
-  # GIT_COMMIT: $(git rev-parse --short "$GITHUB_SHA")
-  # GIT_BRANCH: ${GITHUB_REF#refs/heads/}
+  BUILD_CONFIGURATION: Release
 
 jobs:
   build:
@@ -32,3 +28,4 @@ jobs:
       with:
         sln-path: ${{env.SOLUTION_FILE_PATH}}
         build-config: ${{env.BUILD_CONFIGURATION}}
+        build-type: NIGHTLY

.github/workflows/pr-doc-checker.yml

@@ -14,8 +14,8 @@ env:
 jobs:
   Changelog-Check:
     name: Changelog Mention
-    # If the No Documentation Needed label is set, then workflow will not be executed
-    if: ${{ !contains(github.event.pull_request.labels.*.name, 'No Documentation Needed') }}
+    # If the Skip Changelog label is set, then workflow will not be executed
+    if: ${{ !contains(github.event.pull_request.labels.*.name, 'Skip Changelog') }}
     runs-on: ubuntu-latest
 
     steps:
@@ -31,14 +31,14 @@ jobs:
             exit 0
           else
             echo "It looks like you forgot to update the Changelog! 🧐"
-            echo "Please, mention your changes in 'docs/Whats-New.md' or use [No Documentation Needed] label for your Pull Request."
+            echo "Please, mention your changes in 'docs/Whats-New.md' or ask a maintainer to apply the Skip Changelog label for your Pull Request."
             exit 1
           fi
 
   Credits-Check:
     name: Credits List Mention
-    # If the No Documentation Needed or Bugfix label is set, then workflow will not be executed
-    if: ${{ !contains(github.event.pull_request.labels.*.name, 'No Documentation Needed') && !contains(github.event.pull_request.labels.*.name, 'Bugfix') }}
+    # If the Skip Credits label is set, then workflow will not be executed
+    if: ${{ !contains(github.event.pull_request.labels.*.name, 'Skip Credits') }}
     runs-on: ubuntu-latest
 
     steps:
@@ -54,14 +54,14 @@ jobs:
             exit 0
           else
             echo "It looks like you forgot to update the Credits List! 🧐"
-            echo "Please, mention your contribution in 'CREDITS.md' or use [No Documentation Needed] label for your Pull Request."
+            echo "Please, mention your contribution in 'CREDITS.md' or ask a maintainer to apply the Skip Credits label for your Pull Request."
             exit 1
           fi
 
   Documentation-Check:
     name: Documentation for Changes
-    # If the No Documentation Needed or Bugfix label is set, then workflow will not be executed
-    if: ${{ !contains(github.event.pull_request.labels.*.name, 'No Documentation Needed') && !contains(github.event.pull_request.labels.*.name, 'Bugfix') }}
+    # If the Skip Docs label is set, then workflow will not be executed
+    if: ${{ !contains(github.event.pull_request.labels.*.name, 'Skip Docs') }}
     runs-on: ubuntu-latest
 
     steps:
@@ -85,14 +85,12 @@ jobs:
             exit 0
           else
             echo "It looks like you forgot to add your changes to the docs! 🧐"
-            echo "Please, document your changes or use [No Documentation Needed] label for your Pull Request."
+            echo "Please, document your changes or ask a maintainer to apply the Skip Docs label for your Pull Request."
             exit 1
           fi
 
   Interop-Version-Check:
     name: Interop API Version Updated
-    # If the No Documentation Needed label is set, then workflow will not be executed
-    if: ${{ !contains(github.event.pull_request.labels.*.name, 'No Documentation Needed') }}
     runs-on: ubuntu-latest
 
     steps:
@@ -104,12 +102,12 @@ jobs:
           # Check if any files in src/Interop/ were modified (excluding Version.h itself for initial checks)
           CHANGED_FILES=$(git diff --name-only $(git merge-base origin/$BASE_BRANCH HEAD))
           INTEROP_MODIFIED=$(echo "$CHANGED_FILES" | grep -E "^src/Interop/.*\.(h|cpp)$" | grep -v "^src/Interop/Version\." || true)
-          
+
           if [ -z "$INTEROP_MODIFIED" ]; then
             echo "No Interop files modified. Skipping version check."
             exit 0
           fi
-          
+
           # If Interop files were modified, check if Version.h was also modified
           if echo "$CHANGED_FILES" | grep -q "^src/Interop/Version\.h$"; then
             echo "Thank you for updating the Interop API version! 😋"

.github/workflows/pr-nightly.yml

@@ -10,9 +10,7 @@ env:
   # Configuration type to build.
   # You can convert this to a build matrix if you need coverage of multiple configuration types.
   # https://docs.github.com/actions/learn-github-actions/managing-complex-workflows#using-a-build-matrix
-  BUILD_CONFIGURATION: DevBuild
-  # GIT_COMMIT: $(git rev-parse --short "$GITHUB_SHA")
-  # GIT_BRANCH: ${GITHUB_REF#refs/heads/}
+  BUILD_CONFIGURATION: Release
 
 jobs:
   build:
@@ -30,3 +28,5 @@ jobs:
       with:
         sln-path: ${{env.SOLUTION_FILE_PATH}}
         build-config: ${{env.BUILD_CONFIGURATION}}
+        build-type: NIGHTLY
+

.github/workflows/release.yml

@@ -0,0 +1,87 @@
+name: Release Build
+
+on:
+  release:
+    types: [published]
+
+env:
+  SOLUTION_FILE_PATH: .
+  BUILD_CONFIGURATION: Release
+
+permissions:
+  contents: write
+
+jobs:
+  build:
+    runs-on: windows-2022
+
+    steps:
+    - uses: actions/checkout@v7
+      with:
+        submodules: recursive
+
+    - name: Determine Build Type and Version Info
+      id: info
+      shell: pwsh
+      run: |
+        $tag = "${{ github.ref_name }}"
+        $version = $tag.TrimStart('v')
+        $isPrerelease = "${{ github.event.release.prerelease }}"
+        # Whether the build is a pre-release is decided by Phobos.version.h's PRERELEASE_SUFFIX;
+        # here we only build a release-family build and keep the display name distinct.
+        if ($isPrerelease -eq "true") {
+          $releaseName = "Phobos $tag (Pre-release)"
+        } else {
+          $releaseName = "Phobos $tag"
+        }
+        echo "build-type=RELEASE" >> $env:GITHUB_OUTPUT
+        echo "version=$version" >> $env:GITHUB_OUTPUT
+        echo "release-name=$releaseName" >> $env:GITHUB_OUTPUT
+
+    - name: Build Phobos
+      uses: ./.github/actions/build-phobos
+      with:
+        sln-path: ${{env.SOLUTION_FILE_PATH}}
+        build-config: ${{ env.BUILD_CONFIGURATION }}
+        build-type: ${{ steps.info.outputs.build-type }}
+
+    - name: Extract Release Notes
+      shell: pwsh
+      run: |
+        .\scripts\extract_changelog.ps1 `
+          -Tag "${{ github.ref_name }}" `
+          -WhatsNewPath docs\Whats-New.md `
+          -OutputPath RELEASE_NOTES.md `
+          -LinkBase "https://github.com/${{ github.repository }}/blob/${{ github.ref_name }}/docs"
+
+    - name: Append Changelog to the Release Notes
+      shell: pwsh
+      env:
+        GH_TOKEN: ${{ github.token }}
+      run: |
+        $tag = "${{ github.ref_name }}"
+        # Fetch the text the release author wrote, so the changelog can be appended to it
+        # instead of replacing it. Re-running the workflow must not append a second copy,
+        # so the changelog is wrapped in a marker block that is stripped before re-appending.
+        $existing = (gh api "repos/${{ github.repository }}/releases/tags/$tag" --jq '.body // ""' 2>$null) -join "`n"
+        if ($LASTEXITCODE -ne 0) { $existing = '' }
+        $changelog = (Get-Content -Raw -Path RELEASE_NOTES.md).Trim()
+        $markerStart = '<!-- Phobos changelog start -->'
+        $markerEnd = '<!-- Phobos changelog end -->'
+        $block = "$markerStart`n$changelog`n$markerEnd"
+        # Drop any previously appended changelog block so re-runs replace rather than duplicate
+        $existing = [regex]::Replace($existing, "(?s)$markerStart.*$markerEnd", '').TrimEnd("`r", "`n")
+        $combined = if ([string]::IsNullOrWhiteSpace($existing)) { $block } else { "$existing`n`n$block" }
+        Set-Content -Path RELEASE_NOTES.md -Value $combined -Encoding utf8
+
+    - name: Upload Release Assets
+      uses: softprops/action-gh-release@v2
+      with:
+        name: ${{ steps.info.outputs.release-name }}
+        files: |
+          ${{ env.BUILD_CONFIGURATION }}/Phobos.dll
+          ${{ env.BUILD_CONFIGURATION }}/Phobos.pdb
+          ${{ env.BUILD_CONFIGURATION }}/gamemd.edb
+          ${{ env.BUILD_CONFIGURATION }}/Syringe.exe
+          ${{ env.BUILD_CONFIGURATION }}/Syringe.LICENSE.txt
+        body_path: RELEASE_NOTES.md

.gitignore

@@ -28,3 +28,7 @@ out
 
 # Python virtual environment for docs
 .venv/
+
+# Python bytecode caches
+__pycache__/
+*.py[cod]