Merge pull request 'Version port script and compile check for pull requests' (#19) from port-tooling into master

Reviewed-on: #19

.gitea/scripts/publish_modrinth.mjs

@@ -0,0 +1,164 @@
+#!/usr/bin/env node
+// Publish the jars attached to a Gitea release to Modrinth.
+//
+// Creates one Modrinth version per jar (saturn-client-<version>+<mc>.jar), for
+// that Minecraft version, with Fabric API as a required dependency and the
+// Gitea release notes as the changelog. Versions that already exist on
+// Modrinth are skipped, so the script is safe to re-run.
+//
+// Runs on plain Node (>= 18: fetch, FormData, Blob) with no dependencies, since
+// every Gitea Actions runner has Node to run JavaScript actions.
+//
+// Environment:
+//   TAG               release tag, e.g. 0.1.1-beta
+//   SERVER_URL        public Gitea URL, e.g. https://git.selimaj.dev
+//   REPO              owner/name, e.g. saturnclientmc/saturnclient
+//   MODRINTH_TOKEN    Modrinth PAT with the "Create versions" scope
+//   DRY_RUN           "true" to check everything and print what would be
+//                     published without uploading (no token needed)
+
+const MODRINTH_API = "https://api.modrinth.com/v2";
+const MODRINTH_PROJECT_ID = "i6JDSY9x"; // saturnclient
+const FABRIC_API_PROJECT_ID = "P7dR8mSH";
+const USER_AGENT =
+  "saturnclientmc/saturnclient release workflow (https://git.selimaj.dev/saturnclientmc/saturnclient)";
+
+const JAR_NAME = /^saturn-client-(?<version>.+)\+(?<mc>\d+\.\d+(?:\.\d+)?)\.jar$/;
+
+function fail(message) {
+  console.error(message);
+  process.exit(1);
+}
+
+async function http(url, options = {}) {
+  const res = await fetch(url, {
+    ...options,
+    headers: { "User-Agent": USER_AGENT, ...options.headers },
+  });
+  if (!res.ok) {
+    const error = new Error(`${options.method ?? "GET"} ${url} returned ${res.status}: ${await res.text()}`);
+    error.status = res.status;
+    throw error;
+  }
+  return res;
+}
+
+async function getJson(url) {
+  return (await http(url)).json();
+}
+
+function versionType(tag) {
+  const t = tag.toLowerCase();
+  if (t.includes("alpha")) return "alpha";
+  if (t.includes("beta") || t.includes("rc") || t.includes("pre")) return "beta";
+  return "release";
+}
+
+function compareMc(a, b) {
+  const pa = a.split(".").map(Number);
+  const pb = b.split(".").map(Number);
+  for (let i = 0; i < Math.max(pa.length, pb.length); i++) {
+    const diff = (pa[i] ?? 0) - (pb[i] ?? 0);
+    if (diff !== 0) return diff;
+  }
+  return 0;
+}
+
+async function main() {
+  const { TAG: tag, SERVER_URL, REPO: repo } = process.env;
+  const serverUrl = (SERVER_URL ?? "").replace(/\/+$/, "");
+  const dryRun = (process.env.DRY_RUN ?? "").toLowerCase() === "true";
+  const token = process.env.MODRINTH_TOKEN ?? "";
+
+  if (!tag || !serverUrl || !repo) fail("TAG, SERVER_URL and REPO must be set.");
+  if (!token && !dryRun) {
+    fail("MODRINTH_TOKEN is not set. Add it as a repository secret (Settings → Actions → Secrets).");
+  }
+
+  let release;
+  try {
+    release = await getJson(`${serverUrl}/api/v1/repos/${repo}/releases/tags/${encodeURIComponent(tag)}`);
+  } catch (e) {
+    if (e.status === 404) fail(`No Gitea release with tag ${tag}.`);
+    throw e;
+  }
+  const changelog = release.body ?? "";
+
+  const jars = (release.assets ?? [])
+    .map((asset) => ({ name: asset.name, match: JAR_NAME.exec(asset.name) }))
+    .filter(({ match }) => match)
+    .map(({ name, match }) => ({ name, version: match.groups.version, mc: match.groups.mc }))
+    .sort((a, b) => compareMc(a.mc, b.mc));
+
+  if (jars.length === 0) fail(`Release ${tag} has no saturn-client-*.jar assets. Run the Release workflow first.`);
+
+  for (const jar of jars) {
+    if (jar.version !== tag.replace(/^v/, "")) fail(`${jar.name} is version ${jar.version}, but the release tag is ${tag}.`);
+  }
+
+  const knownGameVersions = new Set((await getJson(`${MODRINTH_API}/tag/game_version`)).map((g) => g.version));
+  const unknown = [...new Set(jars.map((j) => j.mc))].filter((mc) => !knownGameVersions.has(mc));
+  if (unknown.length > 0) fail(`Modrinth doesn't know these Minecraft versions: ${unknown.join(", ")}`);
+
+  const existing = new Set(
+    (await getJson(`${MODRINTH_API}/project/${MODRINTH_PROJECT_ID}/version`)).map((v) => v.version_number),
+  );
+  const kind = versionType(tag);
+  const failed = [];
+
+  for (const { name, version, mc } of jars) {
+    const versionNumber = `${version}+${mc}`;
+
+    if (existing.has(versionNumber)) {
+      console.log(`skip    ${versionNumber}: already on Modrinth`);
+      continue;
+    }
+
+    // Gitea's own download URLs use its internal ROOT_URL, so build a public one.
+    const downloadUrl = `${serverUrl}/${repo}/releases/download/${encodeURIComponent(tag)}/${encodeURIComponent(name)}`;
+
+    const data = {
+      project_id: MODRINTH_PROJECT_ID,
+      name: `Saturn Client ${versionNumber}`,
+      version_number: versionNumber,
+      changelog,
+      dependencies: [{ project_id: FABRIC_API_PROJECT_ID, dependency_type: "required" }],
+      game_versions: [mc],
+      version_type: kind,
+      loaders: ["fabric"],
+      featured: false,
+      status: "listed",
+      file_parts: ["file"],
+      primary_file: "file",
+    };
+
+    if (dryRun) {
+      const probe = await http(downloadUrl, { headers: { Range: "bytes=0-0" } });
+      await probe.arrayBuffer();
+      console.log(`would publish ${versionNumber} (${kind}, Minecraft ${mc}) from ${downloadUrl} [reachable]`);
+      continue;
+    }
+
+    try {
+      const jarBytes = await (await http(downloadUrl)).arrayBuffer();
+
+      const form = new FormData();
+      form.append("data", JSON.stringify(data));
+      form.append("file", new Blob([jarBytes], { type: "application/java-archive" }), name);
+
+      await http(`${MODRINTH_API}/version`, {
+        method: "POST",
+        headers: { Authorization: token },
+        body: form,
+      });
+      console.log(`publish ${versionNumber}: done (${(jarBytes.byteLength / 1_000_000).toFixed(1)} MB)`);
+    } catch (e) {
+      console.error(`publish ${versionNumber}: FAILED ${e.message}`);
+      failed.push(versionNumber);
+    }
+  }
+
+  if (failed.length > 0) fail(`Failed to publish: ${failed.join(", ")}`);
+}
+
+main().catch((e) => fail(e.stack ?? String(e)));

.gitea/workflows/check.yml

@@ -0,0 +1,31 @@
+name: Check
+
+# Compiles every Minecraft version on pull requests and on pushes to master,
+# so a change that breaks one version (e.g. a missed or bad port) fails before
+# it's merged instead of in the release build.
+on:
+  pull_request:
+  push:
+    branches: [master]
+
+jobs:
+  compile:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          submodules: true
+
+      - name: Set up Java 21
+        uses: actions/setup-java@v4
+        with:
+          distribution: temurin
+          java-version: 21
+          cache: gradle
+
+      - name: Compile all versions
+        run: |
+          chmod +x gradlew
+          # --continue reports every version that fails, not just the first.
+          ./gradlew compileJava --no-daemon --stacktrace --continue

.gitea/workflows/modrinth.yml

@@ -0,0 +1,36 @@
+name: Publish to Modrinth
+
+# Publishes the jars already attached to a Gitea release (built by the Release
+# workflow) to Modrinth, one version per Minecraft version. Run it manually
+# after smoke-testing the release. It doesn't rebuild anything, and versions
+# already on Modrinth are skipped, so re-running is safe.
+#
+# Needs a MODRINTH_TOKEN repository secret: a Modrinth PAT with the
+# "Create versions" scope.
+on:
+  workflow_dispatch:
+    inputs:
+      tag:
+        description: Tag of the Gitea release to publish
+        required: true
+      dry_run:
+        description: Only check and print what would be published
+        type: boolean
+        default: false
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Publish to Modrinth
+        env:
+          TAG: ${{ inputs.tag }}
+          DRY_RUN: ${{ inputs.dry_run }}
+          SERVER_URL: ${{ github.server_url }}
+          REPO: ${{ github.repository }}
+          MODRINTH_TOKEN: ${{ secrets.MODRINTH_TOKEN }}
+        # Node is always available on Gitea runners (it runs JavaScript actions).
+        run: node .gitea/scripts/publish_modrinth.mjs

VERSION_GUIDE.md

@@ -1,3 +1,44 @@
 # Version guide
 
-This guide will help you to add or edit minecraft versions.
+How Saturn Client supports several Minecraft versions, and how to change or add one.
+
+## Layout
+
+- `common/`: all version-independent code (mods, UI, cosmetics, the server client). It has no Minecraft dependency and reaches the game only through the interfaces in `org.saturnclient.common`.
+- `versions/<mc>/`: one module per Minecraft version, implementing those interfaces (providers, refs, mixins). Each is a full copy, and they differ only where Minecraft's API differs.
+  - `gradle.properties`: the Minecraft, Yarn, Fabric Loader and Fabric API versions.
+  - `src/`: the version-specific code and the three mixin configs.
+
+`settings.gradle` includes every folder under `versions/` automatically, as the Gradle project `:mc-<mc>`.
+
+## Porting a change to the other versions
+
+Make the change in one version, usually the newest, then run:
+
+```sh
+scripts/port.sh                        # port uncommitted changes to every other version
+scripts/port.sh --dry-run              # see what would apply cleanly first
+scripts/port.sh --to 1.21.9,1.21.10    # only some versions
+scripts/port.sh --commit <rev>         # port what a commit changed instead
+```
+
+The script applies the diff under `versions/<from>/src` to each other version with `git apply --3way`:
+
+- **applied**: the files matched, and nothing else is needed.
+- **CONFLICTS**: that version's code really differs. The file gets normal conflict markers, with the version's own code in `ours` and the ported change in `theirs`. Adapt the change to that version's API and resolve.
+- **already has this change**: nothing to do, which is safe to see when re-running.
+
+Only `src/` is ported. `build.gradle` and `gradle.properties` are version-specific on purpose. Then build everything:
+
+```sh
+./gradlew compileJava
+```
+
+The **Check** workflow runs the same compile on every pull request, so a version that was missed or mis-ported fails before merging.
+
+## Adding a Minecraft version
+
+1. Copy the closest existing version: `cp -r versions/1.21.11 versions/<new>`. Delete its `build/`, `.gradle/` and `run/` folders if present.
+2. In `versions/<new>/gradle.properties`, set `minecraft_version`, `yarn_mappings`, `loader_version` and `fabric_api_version`. The right values are listed at <https://fabricmc.net/develop>.
+3. Build it with `./gradlew :mc-<new>:compileJava` and fix what Minecraft changed. Check the mixin configs in `src/main/resources/*.mixins.json` as well: a mixin whose target changed fails at startup, not at compile time, so launch it with `./gradlew :mc-<new>:runClient`.
+4. The release workflow builds every folder under `versions/`, and "Publish to Modrinth" takes the game version from each jar's name, so neither needs changing.

scripts/port.sh

@@ -0,0 +1,156 @@
+#!/usr/bin/env bash
+# Port a change made in one Minecraft version's code to the other versions.
+#
+# Takes the diff under versions/<from>/src and applies it to versions/<to>/src
+# with `git apply --3way`: it applies cleanly where the files match, and leaves
+# normal merge conflicts only where a version really differs. Only src/ is
+# ported; build.gradle and gradle.properties are version-specific on purpose.
+#
+# Usage:
+#   scripts/port.sh [--from VERSION] [--to V1,V2,...] [--commit REV] [--dry-run]
+#
+#   --from      version the change was made in. Default: the only version with
+#               uncommitted changes (or changed by --commit).
+#   --to        comma-separated versions to port to. Default: all others.
+#   --commit    port the changes a commit made instead of uncommitted changes.
+#   --dry-run   report what would happen without changing anything.
+#
+# Exit status: 0 if every version applied cleanly (or already had the change),
+# 1 if any version has conflicts or failed.
+
+set -euo pipefail
+
+cd "$(git rev-parse --show-toplevel)"
+
+from=""
+to=""
+commit=""
+dry_run=false
+
+while [ $# -gt 0 ]; do
+    case "$1" in
+        --from) from="$2"; shift 2 ;;
+        --to) to="$2"; shift 2 ;;
+        --commit) commit="$2"; shift 2 ;;
+        --dry-run) dry_run=true; shift ;;
+        -h|--help) sed -n '2,20p' "$0" | sed 's/^# \{0,1\}//'; exit 0 ;;
+        *) echo "Unknown option: $1 (see --help)" >&2; exit 2 ;;
+    esac
+done
+
+all_versions=$(ls -d versions/*/ | xargs -n1 basename | sort -t. -k1,1n -k2,2n -k3,3n)
+
+version_exists() {
+    [ -d "versions/$1/src" ]
+}
+
+# Versions with changes, from the working tree or from the given commit.
+changed_versions() {
+    if [ -n "$commit" ]; then
+        git show --name-only --format= "$commit" -- versions/
+    else
+        git diff HEAD --name-only -- versions/
+        git ls-files --others --exclude-standard -- versions/
+    fi | sed -n 's#^versions/\([^/]*\)/src/.*#\1#p' | sort -u
+}
+
+if [ -z "$from" ]; then
+    candidates=$(changed_versions)
+    count=$(printf '%s\n' "$candidates" | grep -c . || true)
+    if [ "$count" -ne 1 ]; then
+        echo "Changes found in ${count} versions (${candidates//$'\n'/, }); pass --from to choose one." >&2
+        exit 2
+    fi
+    from="$candidates"
+fi
+
+version_exists "$from" || { echo "No such version: $from" >&2; exit 2; }
+
+if [ -z "$to" ]; then
+    to=$(printf '%s\n' $all_versions | grep -vx "$from" | paste -sd, -)
+fi
+
+# New files are only included in `git diff HEAD` once git knows about them.
+if [ -z "$commit" ]; then
+    untracked=$(git ls-files --others --exclude-standard -- "versions/$from/src")
+    if [ -n "$untracked" ]; then
+        if $dry_run; then
+            echo "note: new files in versions/$from/src are untracked and won't be ported in a dry run:" >&2
+            printf '  %s\n' $untracked >&2
+        else
+            printf '%s\n' "$untracked" | xargs git add --intent-to-add --
+        fi
+    fi
+fi
+
+# --full-index gives --3way the real blob ids to merge against.
+if [ -n "$commit" ]; then
+    patch=$(git show --full-index --binary --format= "$commit" -- "versions/$from/src")
+else
+    patch=$(git diff HEAD --full-index --binary -- "versions/$from/src")
+fi
+
+if [ -z "$patch" ]; then
+    echo "No changes under versions/$from/src to port." >&2
+    exit 2
+fi
+
+files=$(printf '%s\n' "$patch" | grep -c '^diff --git' || true)
+echo "Porting $files file(s) from $from${commit:+ (commit $commit)}"
+
+from_re=$(printf '%s' "$from" | sed 's/\./\\./g')
+tmp=$(mktemp -d)
+trap 'rm -rf "$tmp"' EXIT
+
+status=0
+IFS=',' read -r -a targets <<< "$to"
+
+for target in "${targets[@]}"; do
+    if [ "$target" = "$from" ]; then
+        continue
+    fi
+    if ! version_exists "$target"; then
+        printf '  %-8s  skipped: no such version\n' "$target"
+        status=1
+        continue
+    fi
+
+    # Point the patch's file headers at the target version.
+    printf '%s\n' "$patch" | sed -E "/^(diff --git |--- |\+\+\+ |rename (from|to) |copy (from|to) )/ s#versions/${from_re}/#versions/${target}/#g" > "$tmp/$target.patch"
+
+    if git apply --check --reverse "$tmp/$target.patch" 2>/dev/null; then
+        printf '  %-8s  already has this change\n' "$target"
+        continue
+    fi
+
+    if $dry_run; then
+        if git apply --check "$tmp/$target.patch" 2>/dev/null; then
+            printf '  %-8s  would apply cleanly\n' "$target"
+        else
+            printf '  %-8s  would need a 3-way merge (possible conflicts)\n' "$target"
+        fi
+        continue
+    fi
+
+    if output=$(git apply --3way "$tmp/$target.patch" 2>&1); then
+        printf '  %-8s  applied\n' "$target"
+    else
+        conflicts=$(git diff --name-only --diff-filter=U -- "versions/$target")
+        if [ -n "$conflicts" ]; then
+            printf '  %-8s  CONFLICTS in:\n' "$target"
+            printf '%s\n' "$conflicts" | sed 's/^/              /'
+        else
+            printf '  %-8s  FAILED:\n' "$target"
+            printf '%s\n' "$output" | sed 's/^/              /'
+        fi
+        status=1
+    fi
+done
+
+if ! $dry_run; then
+    echo
+    echo "Ported changes are staged in the target versions. Resolve any conflicts, then build"
+    echo "the affected versions, e.g. ./gradlew compileJava"
+fi
+
+exit $status