ci(release): beta releases as Codeberg-only pre-releases (#38)

### What this changes

Adds beta releases. Pushing a `release/*` branch whose committed `versionName` is `X.Y.Z-beta.N` makes the new `.gitea/workflows/beta.yaml` run the unit tests, build and sign the APK with the app key, and publish it as a **Codeberg pre-release** (APK + `.sha256`), plus a Gitea pre-release with the R8 mapping. F-Droid (self-hosted and official) and Play never get a beta; Obtainium only offers it with *Include prereleases* on.

- **`scripts/version_info.sh`** is the single source for `versionName` → `versionCode`, used by `release.yaml`, `beta.yaml`, the changelog sync and the store-listing check. From 1.1.0: `X*1000000 + Y*10000 + Z*100 + N` for betas (N = 1–98), `+ 99` for stable, so `1.1.0-beta.1` → `1010001`, `1.1.0` → `1010099`. All 1.0.x versions keep the legacy formula, so `release/v1.0.1` (code `10001`) stays valid.
- **Shared publish scripts:** `scripts/publish_codeberg_release.sh`, `scripts/publish_gitea_release.sh` and `scripts/release_notes.sh`, moved out of `release.yaml`. The stable path behaves as before.
- **Guards:**
  - CI fails a PR whose committed `versionCode` doesn't match its `versionName`.
  - CI fails a PR into `main` that carries a beta version.
  - `release.yaml`'s `detect` refuses a beta on `main` as a backstop.
  - `beta.yaml` refuses a beta of a version that has already shipped as stable.
  - Betas get no store What's New file.
- **Docs:** "Cutting a beta" and the versionCode table in `docs/RELEASING.md`; a note on beta tags in `docs/fdroid-official/README.md`; how to opt in to betas in the README.

### Why

To ship a test build of an upcoming version (e.g. 1.1.0) to opted-in testers before the stable release, without it reaching F-Droid or Play users.

### How it was tested

- `scripts/version_info.sh` against stable, beta, legacy and invalid version names.
- Both publish scripts against a mock forge API: create, re-run (PATCH plus asset replacement), Codeberg's 500-then-retry path, and the skip when no token is set.
- A scratch copy with `1.1.0-beta.1` committed: the version check passes, the changelog sync and `check_store_listing.py --complete` pass without a What's New, the PR-into-main guard trips, and a wrong `versionCode` is rejected.
- `sync_changelog_to_fastlane.sh` and `check_store_listing.py` (with and without `--complete`) still pass on the current `1.0.0`.
- All three workflow files parse as YAML.

Not run on the real runners yet. The first beta push is the live test of `beta.yaml`, which assumes a mirrored branch push starts a workflow on Gitea, the same way pushes to `main` already do.

### Checklist

- [x] No `versionName` / `versionCode` bump
- [x] No `values-*/strings.xml` touched
- [x] `CHANGELOG.md` not updated: this is release infrastructure, not a user-visible change

Co-authored-by: Jean-Luc Makiola <business@jeanlucmakiola.de>
Reviewed-on: https://codeberg.org/jlmakiola/agendula/pulls/38

scripts/check_store_listing.py

@@ -16,6 +16,7 @@ without setup.
 """
 import re
 import struct
+import subprocess
 import sys
 from pathlib import Path
 
@@ -120,10 +121,11 @@ def check_images(locale_dir):
 
 
 def version_code():
-    gradle = (ROOT / "app/build.gradle.kts").read_text()
-    name = re.search(r'versionName\s*=\s*"([^"]+)"', gradle).group(1)
-    parts = (name.split(".") + ["0", "0"])[:3]
-    return int(parts[0]) * 10000 + int(parts[1]) * 100 + int(parts[2])
+    """The committed version's code, or None for a beta (it ships no What's New)."""
+    def info(key):
+        return subprocess.run(["bash", str(ROOT / "scripts/version_info.sh"), key],
+                              check=True, capture_output=True, text=True).stdout.strip()
+    return None if info("channel") == "beta" else int(info("version_code"))
 
 
 def shipped_languages():
@@ -183,7 +185,7 @@ def main():
             err(images / "featureGraphic.png", "required for Play (1024x500, no alpha)")
         if len(list((images / "phoneScreenshots").glob("*"))) < 2:
             err(images / "phoneScreenshots", "Play requires at least 2 phone screenshots")
-        for loc in REQUIRED_LOCALES:
+        for loc in REQUIRED_LOCALES if current is not None else []:
             if not (META / loc / "changelogs" / f"{current}.txt").exists():
                 err(META / loc / "changelogs" / f"{current}.txt", "no What's New for this version")
 

scripts/publish_codeberg_release.sh

@@ -0,0 +1,96 @@
+#!/usr/bin/env bash
+# Publish TAG on Codeberg, which is canonical for tags and releases, with the
+# signed APK and its SHA-256 checksum attached: the direct-download channel
+# that Obtainium follows. Shared by .gitea/workflows/release.yaml (stable) and
+# beta.yaml (pre-release). Run from the repo checkout: it pushes the tag.
+#
+# Codeberg push-mirrors branches and tags to Gitea, but releases aren't git
+# objects and don't sync in either direction, so this pushes the tag straight
+# to Codeberg and creates the release over the API. Skips cleanly when TOKEN is
+# unset; fails loudly on anything else (see release.yaml for why).
+#
+# Env:
+#   TOKEN          CODEBERG_RELEASE_TOKEN (write:repository); empty = skip
+#   API            https://codeberg.org/api/v1/repos/<owner>/<repo>
+#   TAG, SHA       vX.Y.Z[-beta.N] and the commit it marks
+#   PRERELEASE     true | false
+#   NOTES_FILE     release notes (scripts/release_notes.sh)
+#   APK            the signed release APK
+set -euo pipefail
+if [ -z "${TOKEN:-}" ]; then
+  echo "CODEBERG_RELEASE_TOKEN not set — skipping Codeberg publish."
+  exit 0
+fi
+: "${API:?}" "${TAG:?}" "${SHA:?}" "${PRERELEASE:?}" "${NOTES_FILE:?}" "${APK:?}"
+if [ ! -f "$APK" ]; then echo "No release APK at $APK." >&2; exit 1; fi
+
+WORK=$(mktemp -d)
+trap 'rm -rf "$WORK"' EXIT
+
+ASSET_APK="agendula_${TAG}.apk"
+ASSET_SUM="${ASSET_APK}.sha256"
+cp "$APK" "$WORK/$ASSET_APK"
+( cd "$WORK" && sha256sum "$ASSET_APK" > "$ASSET_SUM" )
+
+# Push the tag to Codeberg ourselves. Under Codeberg-canonical the mirror runs
+# Codeberg -> Gitea, so waiting for a tag to arrive from Gitea (what 0.3.2 did)
+# would wait forever. The tag minted on Gitea is in fact *deleted* by the next
+# mirror sync until Codeberg has it, so pushing it here is what makes it
+# durable on both forges.
+#
+# Pushing the ref first and creating the release with NO target_commitish is
+# deliberate: a release POST carrying a target_commitish for a commit or tag
+# Codeberg hasn't received yet is what produced the empty-bodied 500s.
+# Attaching to a ref that already exists doesn't need the API to write one.
+HOST=${API#https://}; HOST=${HOST%%/*}
+REPO=${API#*/repos/}
+git tag -f "$TAG" "$SHA"
+git push -f "https://${REPO%%/*}:${TOKEN}@${HOST}/${REPO}.git" "refs/tags/$TAG"
+
+python3 - "$TAG" "$PRERELEASE" "$NOTES_FILE" <<'PY' > "$WORK/payload.json"
+import json, sys
+tag, pre, notes = sys.argv[1:4]
+print(json.dumps({
+    "tag_name": tag,
+    "name": tag,
+    "body": open(notes).read(),
+    "draft": False,
+    "prerelease": pre == "true",
+}))
+PY
+
+# Create (or update) the release. Codeberg 500s on a POST/GET against a tag it
+# has only just received (the release request outruns the indexing of the ref
+# pushed a moment ago), so a single attempt can fail even though the very same
+# call succeeds seconds later. Retry with backoff, and PATCH in place if a
+# release already exists (re-run safe). A 5xx body still exits curl 0, so the
+# loop, not `set -e`, controls the flow.
+ID=""
+for attempt in 1 2 3 4 5 6; do
+  EXIST=$(curl -s -H "Authorization: token $TOKEN" "$API/releases/tags/$TAG" | jq -r '.id // empty' 2>/dev/null || true)
+  if [ -n "$EXIST" ]; then
+    curl -s -o /dev/null -w "release PATCH HTTP %{http_code}\n" -X PATCH \
+      -H "Authorization: token $TOKEN" -H "Content-Type: application/json" \
+      -d @"$WORK/payload.json" "$API/releases/$EXIST"
+    ID="$EXIST"; break
+  fi
+  CODE=$(curl -s -o "$WORK/response.json" -w "%{http_code}" -X POST \
+    -H "Authorization: token $TOKEN" -H "Content-Type: application/json" \
+    -d @"$WORK/payload.json" "$API/releases")
+  echo "release POST attempt $attempt HTTP $CODE"
+  ID=$(jq -r '.id // empty' "$WORK/response.json" 2>/dev/null || true)
+  [ -n "$ID" ] && break
+  sleep $((attempt * 10))
+done
+if [ -z "$ID" ]; then echo "Could not resolve Codeberg release id after retries." >&2; exit 1; fi
+
+# Attach APK + checksum, replacing any prior asset of the same name.
+for A in "$ASSET_APK" "$ASSET_SUM"; do
+  OLD=$(curl -s -H "Authorization: token $TOKEN" "$API/releases/$ID/assets" \
+    | jq -r --arg n "$A" '.[] | select(.name==$n) | .id')
+  [ -n "$OLD" ] && curl -s -X DELETE -H "Authorization: token $TOKEN" "$API/releases/$ID/assets/$OLD" >/dev/null || true
+  curl -s -X POST -H "Authorization: token $TOKEN" \
+    -F "attachment=@$WORK/$A" \
+    "$API/releases/$ID/assets?name=$A" -o /dev/null -w "asset $A HTTP %{http_code}\n"
+done
+echo "Published $TAG to Codeberg."

scripts/publish_gitea_release.sh

@@ -0,0 +1,76 @@
+#!/usr/bin/env bash
+# Create (or update) the release for TAG on the Gitea build instance, the
+# changelog of record there, and attach the R8 mapping. Shared by
+# .gitea/workflows/release.yaml and beta.yaml.
+#
+# Creating it with target_commitish makes Gitea create the tag at SHA, so the
+# tag only ever marks a fully-shipped version. Upsert, so re-runs are safe.
+#
+# Env:
+#   TOKEN, API     Gitea token and .../api/v1/repos/<owner>/<repo>
+#   TAG, SHA       vX.Y.Z[-beta.N] and the commit it marks
+#   PRERELEASE     true | false
+#   NOTES_FILE     release notes (scripts/release_notes.sh)
+#   MAPPING        optional path to R8's mapping.txt
+set -euo pipefail
+: "${TOKEN:?}" "${API:?}" "${TAG:?}" "${SHA:?}" "${PRERELEASE:?}" "${NOTES_FILE:?}"
+
+WORK=$(mktemp -d)
+trap 'rm -rf "$WORK"' EXIT
+
+python3 - "$TAG" "$SHA" "$PRERELEASE" "$NOTES_FILE" <<'PY' > "$WORK/payload.json"
+import json, sys
+tag, sha, pre, notes = sys.argv[1:5]
+print(json.dumps({
+    "tag_name": tag,
+    "target_commitish": sha,
+    "name": tag,
+    "body": open(notes).read(),
+    "draft": False,
+    "prerelease": pre == "true",
+}))
+PY
+
+# PATCH if a release for the tag already exists, else POST a new one (which
+# also creates the tag at target_commitish).
+ID=$(curl -s -H "Authorization: token $TOKEN" "$API/releases/tags/$TAG" | jq -r '.id // empty' 2>/dev/null || true)
+if [ -n "$ID" ]; then
+  CODE=$(curl -s -o "$WORK/response.json" -w '%{http_code}' -X PATCH \
+    -H "Authorization: token $TOKEN" -H "Content-Type: application/json" \
+    -d @"$WORK/payload.json" "$API/releases/$ID")
+  OK=200
+else
+  CODE=$(curl -s -o "$WORK/response.json" -w '%{http_code}' -X POST \
+    -H "Authorization: token $TOKEN" -H "Content-Type: application/json" \
+    -d @"$WORK/payload.json" "$API/releases")
+  OK=201
+fi
+cat "$WORK/response.json"; echo
+if [ "$CODE" != "$OK" ]; then
+  echo "Gitea release upsert failed with HTTP $CODE (expected $OK)" >&2
+  exit 1
+fi
+ID=$(jq -r '.id' "$WORK/response.json")
+echo "Created/updated Gitea release $TAG at $SHA"
+
+# The R8 mapping keeps user crash stacktraces deobfuscatable. It's not an APK,
+# so it fits the no-binaries rule for this release. Best-effort: never fail a
+# release over it.
+attach_mapping() {
+  local asset="mapping-${TAG#v}.txt.gz" old
+  gzip -c "$MAPPING" > "$WORK/$asset"
+  # Replace any prior asset of the same name (re-run safe).
+  old=$(curl -s -H "Authorization: token $TOKEN" "$API/releases/$ID/assets" \
+    | jq -r --arg n "$asset" '.[] | select(.name==$n) | .id')
+  if [ -n "$old" ]; then
+    curl -s -X DELETE -H "Authorization: token $TOKEN" "$API/releases/$ID/assets/$old" >/dev/null
+  fi
+  curl -s -X POST -H "Authorization: token $TOKEN" \
+    -F "attachment=@$WORK/$asset" \
+    "$API/releases/$ID/assets?name=$asset" -o /dev/null -w "asset $asset HTTP %{http_code}\n"
+}
+if [ -z "${MAPPING:-}" ] || [ ! -f "$MAPPING" ]; then
+  echo "No mapping.txt (R8 off?) — skipping."
+else
+  attach_mapping || echo "warning: could not attach the R8 mapping to $TAG" >&2
+fi

scripts/release_notes.sh

@@ -0,0 +1,29 @@
+#!/usr/bin/env bash
+# Print the forge release notes for VERSION: its `## [VERSION]` section of
+# CHANGELOG.md. A beta (X.Y.Z-beta.N) normally has no section of its own, so it
+# falls back to `## [Unreleased]`, i.e. what the release branch carries so far,
+# under a line saying what a beta is.
+#
+#   scripts/release_notes.sh 1.1.0 > release-notes.md
+set -euo pipefail
+cd "$(dirname "$0")/.."   # repo root
+
+VERSION=${1:?usage: release_notes.sh VERSION}
+
+section() {
+  awk -v ver="$1" '
+    $0 ~ "^## \\[" ver "\\]" { flag = 1; next }
+    /^## \[/ { flag = 0 }
+    flag' CHANGELOG.md | sed -e '/./,$!d'
+}
+
+NOTES=$(section "$VERSION")
+if [[ "$VERSION" == *-beta.* ]]; then
+  [ -n "$NOTES" ] || NOTES=$(section Unreleased)
+  printf '%s\n\n' "**Beta of ${VERSION%%-*}, for testing.** It updates in place to later betas and to the stable release. Obtainium only offers betas with *Include prereleases* switched on; F-Droid and Play never get them."
+fi
+if [ -n "$NOTES" ]; then
+  printf '%s\n' "$NOTES"
+else
+  echo "_No changelog entry for ${VERSION} — see CHANGELOG.md._"
+fi

scripts/sync_changelog_to_fastlane.sh

@@ -11,11 +11,15 @@
 set -euo pipefail
 cd "$(dirname "$0")/.."   # repo root
 
-VERSION=$(grep -oP 'versionName\s*=\s*"\K[^"]+' app/build.gradle.kts)
-[ -n "$VERSION" ] || { echo "No versionName in app/build.gradle.kts" >&2; exit 1; }
-MAJOR=${VERSION%%.*}; rest=${VERSION#*.}; MINOR=${rest%%.*}; PATCH=${rest##*.}
-MAJOR=${MAJOR:-0}; MINOR=${MINOR:-0}; PATCH=${PATCH:-0}
-VERSION_CODE=$(( MAJOR * 10000 + MINOR * 100 + PATCH ))
+VERSION=$(bash scripts/version_info.sh version)
+VERSION_CODE=$(bash scripts/version_info.sh version_code)
+
+# Betas only ship to Codeberg, whose notes come from CHANGELOG.md. A What's New
+# file for one would sit in the tree F-Droid and Play read, so none is wanted.
+if [ "$(bash scripts/version_info.sh channel)" = beta ]; then
+  echo "Beta $VERSION: no store What's New (betas only ship to Codeberg)."
+  exit 0
+fi
 
 # Play rejects a longer "What's New" and F-Droid truncates it in-client.
 MAX_CHARS=${MAX_CHARS:-500}

scripts/version_info.sh

@@ -0,0 +1,87 @@
+#!/usr/bin/env bash
+# The one place that turns the committed versionName into a versionCode and a
+# release channel. The release and beta pipelines, the changelog sync and the
+# store-listing check all read it from here, so the scheme can't drift between
+# them.
+#
+#   versionName           channel   versionCode
+#   X.Y.Z (< 1.1.0)       stable    X*10000   + Y*100   + Z        (legacy)
+#   X.Y.Z-beta.N          beta      X*1000000 + Y*10000 + Z*100 + N  (N = 1..98)
+#   X.Y.Z (>= 1.1.0)      stable    X*1000000 + Y*10000 + Z*100 + 99
+#
+# A beta's code sits below its own stable release and above everything before
+# it, so a beta install updates in place to the next beta and then to the
+# stable version. Every 1.0.x keeps the legacy code it already shipped with;
+# the first new-scheme code (1.1.0-beta.1 -> 1010001) is above all of them.
+#
+#   scripts/version_info.sh          print version, version_code, base_version,
+#                                    channel and prerelease as key=value lines
+#                                    (ready for $GITHUB_OUTPUT)
+#   scripts/version_info.sh <key>    print just that value
+#   scripts/version_info.sh --check  also fail unless the committed versionCode
+#                                    matches; the official F-Droid repo builds
+#                                    the tag as committed, so it must
+set -euo pipefail
+cd "$(dirname "$0")/.."   # repo root
+
+GRADLE="app/build.gradle.kts"
+NAME=$(grep -oP 'versionName\s*=\s*"\K[^"]+' "$GRADLE" || true)
+COMMITTED=$(grep -oP 'versionCode\s*=\s*\K[0-9]+' "$GRADLE" || true)
+[ -n "$NAME" ] || { echo "No versionName in $GRADLE" >&2; exit 1; }
+
+if [[ ! "$NAME" =~ ^([0-9]+)\.([0-9]+)\.([0-9]+)(-beta\.([0-9]+))?$ ]]; then
+  echo "versionName '$NAME' is neither X.Y.Z nor X.Y.Z-beta.N" >&2
+  exit 1
+fi
+MAJOR=$((10#${BASH_REMATCH[1]})); MINOR=$((10#${BASH_REMATCH[2]})); PATCH=$((10#${BASH_REMATCH[3]}))
+BETA=${BASH_REMATCH[5]:+$((10#${BASH_REMATCH[5]}))}
+BASE="$MAJOR.$MINOR.$PATCH"
+
+if [ "$MINOR" -gt 99 ] || [ "$PATCH" -gt 99 ]; then
+  echo "versionName '$NAME': MINOR and PATCH each have room for 0-99" >&2
+  exit 1
+fi
+
+LEGACY=$(( MAJOR * 10000 + MINOR * 100 + PATCH ))
+if [ -n "$BETA" ]; then
+  if [ "$LEGACY" -lt 10100 ]; then
+    echo "versionName '$NAME': betas start at 1.1.0; 1.0.x codes have no room for them" >&2
+    exit 1
+  fi
+  if [ "$BETA" -lt 1 ] || [ "$BETA" -gt 98 ]; then
+    echo "versionName '$NAME': beta number must be 1-98 (99 is the stable release)" >&2
+    exit 1
+  fi
+  CHANNEL=beta
+  CODE=$(( MAJOR * 1000000 + MINOR * 10000 + PATCH * 100 + BETA ))
+elif [ "$LEGACY" -lt 10100 ]; then
+  CHANNEL=stable
+  CODE=$LEGACY
+else
+  CHANNEL=stable
+  CODE=$(( MAJOR * 1000000 + MINOR * 10000 + PATCH * 100 + 99 ))
+fi
+
+# Betas are always pre-releases; so was everything before 1.0.0.
+if [ "$CHANNEL" = beta ] || [ "$MAJOR" = 0 ]; then PRERELEASE=true; else PRERELEASE=false; fi
+
+case "${1:-}" in
+  "")
+    printf 'version=%s\nversion_code=%s\nbase_version=%s\nchannel=%s\nprerelease=%s\n' \
+      "$NAME" "$CODE" "$BASE" "$CHANNEL" "$PRERELEASE"
+    ;;
+  --check)
+    if [ "$COMMITTED" != "$CODE" ]; then
+      echo "ERROR: $GRADLE has versionCode = ${COMMITTED:-<none>}, but versionName '$NAME' needs $CODE." >&2
+      echo "Set versionCode = $CODE (see docs/RELEASING.md for the scheme)." >&2
+      exit 1
+    fi
+    echo "OK: versionName $NAME -> versionCode $CODE ($CHANNEL)."
+    ;;
+  version) echo "$NAME" ;;
+  version_code) echo "$CODE" ;;
+  base_version) echo "$BASE" ;;
+  channel) echo "$CHANNEL" ;;
+  prerelease) echo "$PRERELEASE" ;;
+  *) echo "Unknown key '$1'" >&2; exit 2 ;;
+esac