ci: build Windows artifacts and prepare tagged releases

Author: jinghaihan

.github/workflows/build.yml

@@ -0,0 +1,35 @@
+name: build
+
+on:
+  push:
+    branches: [master]
+  pull_request:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  windows:
+    runs-on: windows-2025
+    steps:
+      - uses: actions/checkout@v7
+
+      - uses: microsoft/setup-msbuild@v3
+
+      - uses: actions/setup-python@v6
+        with:
+          python-version: '3.13'
+
+      - name: Build .NET Framework projects
+        run: msbuild FireEmblemThreeHouse.sln /t:Rebuild /p:Configuration=Release /p:Platform="Any CPU" /v:minimal
+
+      - name: Package and verify downloads
+        run: python tools/package.py
+
+      - uses: actions/upload-artifact@v7
+        with:
+          name: fe3h-editor-windows
+          path: dist/*
+          if-no-files-found: error
+          retention-days: 14

.github/workflows/release.yml

@@ -0,0 +1,67 @@
+name: release
+
+on:
+  push:
+    tags:
+      - 'v*'
+
+permissions:
+  contents: write
+
+jobs:
+  windows:
+    runs-on: windows-2025
+    steps:
+      - uses: actions/checkout@v7
+
+      - uses: microsoft/setup-msbuild@v3
+
+      - uses: actions/setup-python@v6
+        with:
+          python-version: '3.13'
+
+      - name: Verify tag version
+        shell: pwsh
+        run: |
+          $version = (Get-Content VERSION -Raw).Trim()
+          if ($env:GITHUB_REF_NAME -ne "v$version") { throw "Tag does not match VERSION" }
+
+      - name: Build .NET Framework projects
+        run: msbuild FireEmblemThreeHouse.sln /t:Rebuild /p:Configuration=Release /p:Platform="Any CPU" /v:minimal
+
+      - name: Package and verify downloads
+        run: python tools/package.py
+
+      - uses: actions/upload-artifact@v7
+        with:
+          name: fe3h-editor-release
+          path: dist/*
+          if-no-files-found: error
+
+      - name: Publish prerelease
+        shell: pwsh
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          $version = (Get-Content VERSION -Raw).Trim()
+          gh release create $env:GITHUB_REF_NAME `
+            dist/FETH_SaveEditor.exe `
+            "dist/fe3h-editor-v$version.zip" `
+            dist/SHA256SUMS `
+            --verify-tag --generate-notes --prerelease
+          if ($LASTEXITCODE -ne 0) { throw "Failed to publish release" }
+
+      - name: Verify downloadable files
+        shell: pwsh
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          $version = (Get-Content VERSION -Raw).Trim()
+          New-Item -ItemType Directory -Path release-download | Out-Null
+          gh release download $env:GITHUB_REF_NAME --dir release-download
+          if ($LASTEXITCODE -ne 0) { throw "Failed to download release" }
+          foreach ($name in @("FETH_SaveEditor.exe", "fe3h-editor-v$version.zip")) {
+            $expected = (Get-FileHash "dist/$name" -Algorithm SHA256).Hash
+            $actual = (Get-FileHash "release-download/$name" -Algorithm SHA256).Hash
+            if ($expected -ne $actual) { throw "Download checksum mismatch: $name" }
+          }

.gitignore

@@ -3,3 +3,4 @@ DataUnpacker/obj/
 SaveEditor/bin/
 DataUnpacker/bin/
 *.user
+dist/

VERSION

@@ -0,0 +1 @@
+0.1.0

docs/RELEASING.md

@@ -0,0 +1,14 @@
+# Building and releasing
+
+`VERSION` is this fork's release number. The supported game version is 1.2.0.
+
+Every push to `master`, pull request, or manual run of the [build workflow](../.github/workflows/build.yml) builds both .NET Framework 4.7.2 projects on Windows. Its `fe3h-editor-windows` artifact contains a standalone save editor executable, a ZIP with both tools and their config files, and SHA-256 checksums. Artifacts are retained for 14 days.
+
+To publish after reviewing a successful Windows build:
+
+1. Update `VERSION` in a Conventional Commit and push `master`.
+2. Wait for the build workflow to pass for that commit.
+3. Run `python3 tools/release.py --current --check` to check readiness.
+4. Run `python3 tools/release.py --current` to create and push an annotated version tag.
+
+The [release workflow](../.github/workflows/release.yml) builds the tagged source on Windows, packages the same files, publishes a prerelease, then downloads and checks the published files. The release script does not create a release until the version tag is pushed. It requires GitHub CLI authentication.

tools/package.py

@@ -0,0 +1,72 @@
+#!/usr/bin/env python3
+"""Package the Windows Release build for CI downloads and GitHub Releases."""
+
+from __future__ import annotations
+
+import argparse
+import hashlib
+import re
+import shutil
+import zipfile
+from pathlib import Path
+
+
+ROOT = Path(__file__).resolve().parent.parent
+FILES = {
+    "FETH_SaveEditor.exe": ROOT / "SaveEditor/bin/Release/FETH_SaveEditor.exe",
+    "FETH_SaveEditor.exe.config": ROOT / "SaveEditor/bin/Release/FETH_SaveEditor.exe.config",
+    "DataUnpacker.exe": ROOT / "DataUnpacker/bin/Release/DataUnpacker.exe",
+    "DataUnpacker.exe.config": ROOT / "DataUnpacker/bin/Release/DataUnpacker.exe.config",
+    "README.md": ROOT / "README.md",
+}
+
+
+def version() -> str:
+    value = (ROOT / "VERSION").read_text(encoding="utf-8").strip()
+    if not re.fullmatch(r"\d+\.\d+\.\d+(?:-[0-9A-Za-z]+(?:[.-][0-9A-Za-z]+)*)?", value):
+        raise ValueError(f"invalid VERSION: {value}")
+    return value
+
+
+def digest(path: Path) -> str:
+    sha256 = hashlib.sha256()
+    with path.open("rb") as source:
+        for chunk in iter(lambda: source.read(1024 * 1024), b""):
+            sha256.update(chunk)
+    return sha256.hexdigest()
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--output", type=Path, default=ROOT / "dist")
+    args = parser.parse_args()
+
+    for name, source in FILES.items():
+        if not source.is_file() or source.stat().st_size == 0:
+            raise FileNotFoundError(f"missing build file: {name} ({source})")
+
+    output = args.output.resolve()
+    output.mkdir(parents=True, exist_ok=True)
+    editor = output / "FETH_SaveEditor.exe"
+    package = output / f"fe3h-editor-v{version()}.zip"
+    checksums = output / "SHA256SUMS"
+
+    shutil.copy2(FILES["FETH_SaveEditor.exe"], editor)
+    with zipfile.ZipFile(package, "w", compression=zipfile.ZIP_DEFLATED, compresslevel=9) as archive:
+        for name, source in FILES.items():
+            archive.write(source, name)
+
+    with zipfile.ZipFile(package) as archive:
+        if archive.testzip() is not None or set(archive.namelist()) != set(FILES):
+            raise ValueError("release ZIP failed verification")
+
+    checksums.write_text(
+        "".join(f"{digest(path)}  {path.name}\n" for path in (editor, package)),
+        encoding="utf-8",
+    )
+    for path in (editor, package, checksums):
+        print(path)
+
+
+if __name__ == "__main__":
+    main()

tools/release.py

@@ -0,0 +1,63 @@
+#!/usr/bin/env python3
+"""Tag a reviewed master commit; GitHub Actions builds and publishes it."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import subprocess
+from pathlib import Path
+
+from package import ROOT, version
+
+
+def run(*args: str) -> str:
+    result = subprocess.run(args, cwd=ROOT, check=True, text=True, capture_output=True)
+    return result.stdout.strip()
+
+
+def check_ready(tag: str) -> None:
+    if Path(run("git", "rev-parse", "--show-toplevel")) != ROOT:
+        raise ValueError("run from this repository")
+    if run("git", "branch", "--show-current") != "master":
+        raise ValueError("releases must come from master")
+    if run("git", "status", "--porcelain"):
+        raise ValueError("commit working-tree changes first")
+
+    run("git", "fetch", "origin", "master", "--tags")
+    head = run("git", "rev-parse", "HEAD")
+    if head != run("git", "rev-parse", "origin/master"):
+        raise ValueError("local master is not synchronized with origin/master")
+    if run("git", "tag", "--list", tag):
+        raise ValueError(f"tag already exists: {tag}")
+
+    builds = json.loads(run(
+        "gh", "run", "list", "--workflow", "build.yml", "--commit", head,
+        "--json", "conclusion,status", "--limit", "20",
+    ))
+    if not any(build["status"] == "completed" and build["conclusion"] == "success" for build in builds):
+        raise ValueError("wait for a successful Windows build of this commit before releasing")
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--current", action="store_true", required=True)
+    parser.add_argument("--check", action="store_true", help="validate without tagging")
+    parser.add_argument("--yes", action="store_true", help="skip the confirmation prompt")
+    args = parser.parse_args()
+
+    tag = f"v{version()}"
+    check_ready(tag)
+    if args.check:
+        print(f"Ready to publish {tag} from {run('git', 'rev-parse', '--short', 'HEAD')}")
+        return
+    if not args.yes and input(f"Create and push {tag}? [y/N] ").lower() not in ("y", "yes"):
+        return
+
+    run("git", "tag", "-a", tag, "-m", tag)
+    run("git", "push", "origin", tag)
+    print(f"Pushed {tag}. Check the release workflow before sharing its downloads.")
+
+
+if __name__ == "__main__":
+    main()