ci(release): attach per-version notes from PREVIOUS_HISTORY.md to releases
Per-version user-facing changelog moved out of the README table into PREVIOUS_HISTORY.md (newest-first sections, Development Plan §11.1). On tag push the workflow now harvests the matching section via scripts/ci/release-notes.py and uses it as the release description, uploading an Incido-<version>-changes.md beside the APKs; a missing section falls back to the plain default description. CONTRIBUTING §5 documents the new release-notes maintenance step.
This commit is contained in:
1 parent
576080c8b5
commit
7b6187f99a
5 files changed
+357
-3
No files matched your search
Executable
+54
@@ -0,0 +1,54 @@
|
||||
#!/usr/bin/env bash
|
||||
# One-off helper: attach PREVIOUS_HISTORY.md notes to EXISTING Gitea
|
||||
# releases that were published before the automatic pipeline existed.
|
||||
#
|
||||
# TOKEN=<gitea-token-with-release-write> ./backfill-release-notes.sh [version ...]
|
||||
#
|
||||
# With no arguments it walks every section of PREVIOUS_HISTORY.md and
|
||||
# silently skips versions that have no release entry / no section.
|
||||
# Idempotent: replaces both the description and the changes-file asset.
|
||||
set -euo pipefail
|
||||
|
||||
API="${GITEA_API:-https://git.trevena.info/api/v1/repos/nick/incido}"
|
||||
: "${TOKEN:?Set TOKEN to a Gitea token with release write access}"
|
||||
ROOT="$(cd "$(dirname "$0")/../.." && pwd)"
|
||||
NOTES_PY="$ROOT/scripts/ci/release-notes.py"
|
||||
|
||||
if [ "$#" -gt 0 ]; then
|
||||
VERSIONS=("$@")
|
||||
else
|
||||
mapfile -t VERSIONS < <(grep -oE '^## v[0-9]+(\.[0-9]+)+' "$ROOT/PREVIOUS_HISTORY.md" | sed 's/^## v//')
|
||||
fi
|
||||
|
||||
for V in "${VERSIONS[@]}"; do
|
||||
TAG="v$V"
|
||||
RID=$(curl -s "$API/releases/tags/$TAG" \
|
||||
-H "Authorization: token $TOKEN" \
|
||||
| python3 -c "import sys,json; print(json.load(sys.stdin).get('id','') or '')")
|
||||
if [ -z "$RID" ]; then echo "skip $TAG (no release entry)"; continue; fi
|
||||
|
||||
NOTES="/tmp/Incido-$V-changes.md"
|
||||
if ! python3 "$NOTES_PY" "$V" --out "$NOTES"; then
|
||||
echo "skip $TAG (no PREVIOUS_HISTORY.md section)"; continue
|
||||
fi
|
||||
|
||||
# Refresh the description.
|
||||
REL_NOTES_FILE="$NOTES" python3 -c "import json,os; print(json.dumps({'body': open(os.environ['REL_NOTES_FILE'],encoding='utf-8').read()}))" \
|
||||
> /tmp/body_patch.json
|
||||
curl -s -X PATCH "$API/releases/$RID" \
|
||||
-H "Authorization: token $TOKEN" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d @/tmp/body_patch.json > /dev/null
|
||||
|
||||
# Replace a stale changes-file asset, then upload the fresh one.
|
||||
curl -s "$API/releases/$RID/assets" -H "Authorization: token $TOKEN" \
|
||||
| REL_ASSET_NAME="Incido-$V-changes.md" python3 -c "import sys,json,os; [print(a['id']) for a in json.load(sys.stdin) if a['name']==os.environ['REL_ASSET_NAME']]" \
|
||||
| while read -r AID; do
|
||||
curl -s -X DELETE "$API/releases/$RID/assets/$AID" -H "Authorization: token $TOKEN" > /dev/null
|
||||
done
|
||||
curl -s -f -X POST "$API/releases/$RID/assets?name=Incido-$V-changes.md" \
|
||||
-H "Authorization: token $TOKEN" \
|
||||
-F "attachment=@$NOTES" --max-time 600 > /dev/null \
|
||||
|| echo "WARN $TAG: description patched, but the changes-file upload failed"
|
||||
echo "done $TAG"
|
||||
done
|
||||
Executable
+88
@@ -0,0 +1,88 @@
|
||||
#!/usr/bin/env python3
|
||||
"""Extract the release-notes section for one version from PREVIOUS_HISTORY.md.
|
||||
|
||||
Incido publishes its user-facing changelog through the Gitea Releases page:
|
||||
for every tag push, `.gitea/workflows/release.yml` calls this script with
|
||||
the released version. The matching `## v<VERSION> — <DATE>` section of
|
||||
PREVIOUS_HISTORY.md becomes the release description and is also uploaded
|
||||
next to the APKs as `Incido-<VERSION>-changes.md`.
|
||||
|
||||
Usage:
|
||||
release-notes.py <version> [--out FILE] [--history FILE] [--no-footer]
|
||||
|
||||
Exits 0 and prints the Markdown (to --out FILE or stdout) when the section
|
||||
exists; exits 1 (message on stderr) when it doesn't — the workflow then
|
||||
falls back to its generic "Release <tag>" body.
|
||||
"""
|
||||
|
||||
import argparse
|
||||
import re
|
||||
import sys
|
||||
from pathlib import Path
|
||||
|
||||
# "## v0.3.8.0 — 2026-09-16" -> group(1) = "0.3.8.0"
|
||||
HEADING = re.compile(r"^##\s+v?([0-9]+(?:\.[0-9]+)*)\b")
|
||||
|
||||
FOOTER = (
|
||||
"\n\n---\n\n"
|
||||
"_Full history: PREVIOUS_HISTORY.md at the repository root. "
|
||||
"In-depth developer notes: Incido Development Plan \u00a710._\n"
|
||||
)
|
||||
|
||||
|
||||
def extract(history_text: str, version: str, footer: bool) -> str | None:
|
||||
wanted = version.lstrip("vV").strip()
|
||||
collected: list[str] = []
|
||||
in_section = False
|
||||
for line in history_text.splitlines():
|
||||
match = HEADING.match(line)
|
||||
if match:
|
||||
in_section = match.group(1) == wanted
|
||||
if in_section:
|
||||
collected.append(line)
|
||||
if not collected:
|
||||
return None
|
||||
body = "\n".join(collected).rstrip()
|
||||
if not body:
|
||||
return None
|
||||
return body + (FOOTER if footer else "")
|
||||
|
||||
|
||||
def main() -> int:
|
||||
parser = argparse.ArgumentParser(description=__doc__.splitlines()[0])
|
||||
parser.add_argument("version", help="Version or tag, e.g. 0.3.8.0 or v0.3.8.0")
|
||||
parser.add_argument("--out", type=Path, default=None,
|
||||
help="Write the notes to this file instead of stdout")
|
||||
parser.add_argument("--history", type=Path, default=None,
|
||||
help="Path to PREVIOUS_HISTORY.md "
|
||||
"(default: repo root, two levels above scripts/ci/)")
|
||||
parser.add_argument("--no-footer", action="store_true",
|
||||
help="Omit the standard cross-reference footer")
|
||||
args = parser.parse_args()
|
||||
|
||||
history_path = args.history or (
|
||||
Path(__file__).resolve().parents[2] / "PREVIOUS_HISTORY.md"
|
||||
)
|
||||
if not history_path.is_file():
|
||||
print(f"release-notes: history file not found: {history_path}",
|
||||
file=sys.stderr)
|
||||
return 1
|
||||
|
||||
notes = extract(history_path.read_text(encoding="utf-8"),
|
||||
args.version, footer=not args.no_footer)
|
||||
if notes is None:
|
||||
print(f"release-notes: no changelog section for {args.version} "
|
||||
f"in {history_path.name}", file=sys.stderr)
|
||||
return 1
|
||||
|
||||
if args.out:
|
||||
args.out.write_text(notes, encoding="utf-8")
|
||||
print(f"Wrote {len(notes)} chars for v{args.version.lstrip('vV')} "
|
||||
f"to {args.out}")
|
||||
else:
|
||||
sys.stdout.write(notes)
|
||||
return 0
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
sys.exit(main())
|
||||
Reference in new issue
Block a user