diff --git a/.github/workflows/upstream-watch.yml b/.github/workflows/upstream-watch.yml new file mode 100644 index 0000000..57f94f9 --- /dev/null +++ b/.github/workflows/upstream-watch.yml @@ -0,0 +1,43 @@ +name: Upstream watch + +on: + schedule: + - cron: '17 9 1 * *' + workflow_dispatch: + pull_request: + paths: + - '.github/workflows/upstream-watch.yml' + - 'maintenance/upstream-watch.json' + - 'tools/upstream_watch.py' + - 'tests/test_upstream_watch.py' + push: + branches: [main] + paths: + - '.github/workflows/upstream-watch.yml' + - 'maintenance/upstream-watch.json' + - 'tools/upstream_watch.py' + - 'tests/test_upstream_watch.py' + +permissions: + contents: read + +jobs: + report: + runs-on: ubuntu-24.04 + timeout-minutes: 10 + steps: + - uses: actions/checkout@v7 + - name: Test version filtering, pagination and failure reporting + run: python3 tests/test_upstream_watch.py + - name: Check upstream versions and write review report + env: + GH_TOKEN: ${{ github.token }} + run: python3 tools/upstream_watch.py --output '${{ runner.temp }}/upstream-watch' + - name: Save upstream review report + if: always() + uses: actions/upload-artifact@v7 + with: + name: upstream-review-report + path: ${{ runner.temp }}/upstream-watch + retention-days: 90 + if-no-files-found: warn diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 6ab1afa..ff18b32 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -79,3 +79,10 @@ or app extra. This creates local files and does not publish a GitHub release. The repository's regression checks and their prerequisites are documented in [tests/README.md](tests/README.md). GitHub Actions runs them on pull requests. + +## Upstream compatibility maintenance + +The [monthly upstream watch](maintenance/README.md) reports new release tags and +links to component-specific review/test guidance. It does not modify the theme +or establish compatibility automatically. Update review baselines only after +recording the relevant checks and limits in `COMPATIBILITY.md`. diff --git a/README.md b/README.md index 73c68d0..4ba9960 100644 --- a/README.md +++ b/README.md @@ -166,6 +166,7 @@ for tested versions and coverage limits. - [Installation, updates, removal and manual configuration](INSTALLING.md) - [Accent choices and contrast](ACCENT_COLORS.md) +- [Monthly upstream watch and compatibility maintenance](https://github.com/librerob/adwaita-amoled/blob/main/maintenance/README.md) - [Development, building and testing](https://github.com/librerob/adwaita-amoled/blob/main/CONTRIBUTING.md) - Detailed color reviews: [readability](COLOR_READABILITY.md) and [compound states and file coverage](COLOR_COMPLETENESS.md) diff --git a/maintenance/README.md b/maintenance/README.md new file mode 100644 index 0000000..2e53b8b --- /dev/null +++ b/maintenance/README.md @@ -0,0 +1,74 @@ +# Automated upstream watch + +[Open Upstream watch in GitHub Actions](https://github.com/librerob/adwaita-amoled/actions/workflows/upstream-watch.yml). + +The workflow runs on the first of each month, at 09:17 UK winter time / 10:17 UK +summer time (GitHub cron uses 09:17 UTC). GitHub may delay scheduled runs. +For an immediate check, open that page, choose **Run workflow**, select `main` +and confirm **Run workflow**. No personal token or additional secret is needed. + +Open the completed run's **Summary** for its component table and upstream +comparison/source links. Download **upstream-review-report** under Artifacts +for Markdown and JSON copies; reports are retained for 90 days. New versions +appear as **review-needed** and workflow warnings. Finding an update is a +successful check, not a failing theme test. This does not send custom email, +create issues, or guarantee a notification; check the Actions report to review +updates. API/configuration failures fail the workflow and must not be read as +“up to date.” GitHub's own failure notifications depend on account preferences. + +## What it checks + +The catalog tracks GTK3, current/future GTK majors, libadwaita, GNOME desktop +release manifests, current/future GNOME Shell majors, the supported Shell 46 +maintenance series, Cinnamon, Muffin, Xfce panel, Xfwm4 integration, MATE desktop, +Marco and Budgie. It uses the projects' public upstream GitHub repositories or +mirrors. Primary GitLab releases may reach a mirror later. + +Baseline versions come from [the compatibility review](../COMPATIBILITY.md) +and the pinned Shell metadata. A baseline records the last review point; it +is not a claim that every desktop session or future point release is tested. +The MATE desktop baseline is the beginning of the reviewed 1.28 series; +Marco has its separate, specifically tested version. + +All tag pages are considered, rather than trusting the first page or lexical +ordering. Numeric version comparison avoids mistakes such as ordering `.9` +after `.10`. Prerelease suffixes and build/branch tags are excluded. GTK, +libadwaita, Cinnamon/Muffin, Xfce and MATE/Marco use explicitly configured even +minor series; Budgie and modern GNOME Shell do not. Minor versions 90 and above +are excluded as development versions. These are conservative **tag rules**, +not a substitute for reading official release announcements. A project changing +its release scheme may require updating the rules. Pinned Shell tag commit +changes are flagged, and missing baseline tags or incomplete pagination produce +errors rather than a green “no-new-tag” result. + +## Reviewing an update + +1. Follow the comparison and source links. Read NEWS/release notes and changes + to the relevant styles, widget nodes, assets, settings schemas or decorations. +2. Run the affected checks listed in the report and [tests guide](../tests/README.md) + against the new dependency version. For a new desktop major, add native/session + coverage before declaring it supported. Existing Ubuntu test images do not + automatically upgrade to every new upstream release. +3. Reproduce suspected regressions before fixing them; rerun affected tests after + a fix. A release can need review without requiring any theme modification. +4. Record versions, evidence and limits in `COMPATIBILITY.md`. Then update the + relevant `baseline_tag` in `upstream-watch.json`; if it has a pinned + `baseline_commit`, update that review commit too. Do not advance baselines + just to clear warnings. The watch never edits upstream imports or baselines. + +The workflow also runs when its code/configuration changes, so it can be tested +before merging. It is read-only and does not change colors, installer behavior, +release assets, tags or icon inheritance. Its files are not added to the +installer runtime payload. No new theme release is needed just for this watch. + +For local development, Python 3.11+ and authenticated GitHub CLI are needed: + +```bash +python3 tests/test_upstream_watch.py +python3 tools/upstream_watch.py --output /tmp/adwaita-upstream-report +``` + +GitHub can disable scheduled workflows on inactive public repositories after +60 days. If reports stop appearing, check the Actions page for a re-enable +banner. The watch does not detect unreleased branch changes, distribution-only +patches, arbitrary application CSS or hardware-specific rendering problems. diff --git a/maintenance/upstream-watch.json b/maintenance/upstream-watch.json new file mode 100644 index 0000000..c51b15c --- /dev/null +++ b/maintenance/upstream-watch.json @@ -0,0 +1,202 @@ +{ + "version": 1, + "components": [ + { + "id": "gtk3", + "name": "GTK3 / Adwaita", + "repo": "GNOME/gtk", + "baseline_tag": "3.24.52", + "path": "gtk/theme/Adwaita", + "focus": "Review Adwaita widget selectors, states and resource changes.", + "tests": "tests/test_runtime.py, tests/test_borders.py and GTK3 accent/native consumers.", + "even_minor": true, + "min_major": 3, + "prefixes": [ + "", + "v" + ], + "max_major": 3 + }, + { + "id": "gtk", + "name": "GTK / Default (current and future majors)", + "repo": "GNOME/gtk", + "baseline_tag": "4.24.1", + "path": "gtk/theme/Default", + "focus": "Review default style imports, widget nodes and public CSS changes. A new major needs a separate compatibility decision.", + "tests": "tests/test_runtime.py, tests/border_native.py and tests/accent_native.py gtk on the new toolkit.", + "even_minor": true, + "min_major": 4, + "prefixes": [ + "", + "v" + ] + }, + { + "id": "libadwaita", + "name": "libadwaita", + "repo": "GNOME/libadwaita", + "baseline_tag": "1.10.0", + "path": "src/stylesheet", + "focus": "Review named colors, CSS variables, light/dark derivation and new widget classes.", + "tests": "Modern and legacy overrides; tests/test_runtime.py and all-accent native GTK checks.", + "even_minor": true, + "min_major": 1, + "prefixes": [ + "", + "v" + ] + }, + { + "id": "gnome", + "name": "GNOME desktop release", + "repo": "GNOME/gnome-build-meta", + "baseline_tag": "51.0", + "path": "elements", + "focus": "Review release NEWS and component versions; this does not establish a complete desktop/login-session test.", + "tests": "Targeted Shell/toolkit checks and a real desktop smoke test when available.", + "even_minor": false, + "min_major": 40, + "prefixes": [ + "", + "v" + ] + }, + { + "id": "shell", + "name": "GNOME Shell (current and future majors)", + "repo": "GNOME/gnome-shell", + "baseline_tag": "51.1", + "path": "data/theme", + "focus": "Review Shell Sass, assets and menu/control structure. New majors remain unsupported until tested; do not overwrite pinned sources automatically.", + "tests": "tests/gnome-shell native pointer/Wayland fixtures and all-accent Shell checks.", + "even_minor": false, + "min_major": 40, + "prefixes": [ + "", + "v" + ], + "baseline_commit": "33da06854e229c256afd5872fedd83c28cbfa176" + }, + { + "id": "shell46", + "name": "GNOME Shell 46 maintenance", + "repo": "GNOME/gnome-shell", + "baseline_tag": "46.10", + "path": "data/theme", + "focus": "Review maintenance changes to the supported Shell 46 baseline.", + "tests": "GNOME Shell 46 build/source and native pointer/accent tests.", + "even_minor": false, + "min_major": 46, + "prefixes": [ + "", + "v" + ], + "max_major": 46, + "baseline_commit": "49fa85b2fead489d5c1ce50ecaf28a114c831f1e" + }, + { + "id": "cinnamon", + "name": "Cinnamon", + "repo": "linuxmint/cinnamon", + "baseline_tag": "6.6.9", + "path": "data/theme", + "focus": "Review shell selectors, menu/calendar/taskbar states and Settings preview lookup.", + "tests": "tests/cinnamon_colors.py, tests/cinnamon_accent_update.py and tests/cinnamon_theme_previews.py.", + "even_minor": true, + "min_major": 6, + "prefixes": [ + "", + "v" + ] + }, + { + "id": "muffin", + "name": "Muffin", + "repo": "linuxmint/muffin", + "baseline_tag": "6.6.3", + "path": "src", + "focus": "Review decoration/theme-loader changes and window states.", + "tests": "Native Metacity/Muffin frame rendering and window-state checks.", + "even_minor": true, + "min_major": 6, + "prefixes": [ + "", + "v" + ] + }, + { + "id": "xfce-panel", + "name": "Xfce panel", + "repo": "xfce-mirror/xfce4-panel", + "baseline_tag": "xfce4-panel-4.20.8", + "path": "plugins", + "focus": "Review GTK panel selectors and active/hover states.", + "tests": "Real panel, menu and task-button tests; GTK parsing and accent checks.", + "even_minor": true, + "min_major": 4, + "prefixes": [ + "xfce4-panel-" + ] + }, + { + "id": "xfwm", + "name": "Xfwm4 integration", + "repo": "xfce-mirror/xfwm4", + "baseline_tag": "xfwm4-4.20.0", + "path": "src", + "focus": "Review integration boundaries. This repository does not supply Xfwm4 decorations.", + "tests": "Xfce GTK/panel integration smoke test; do not claim new decoration support.", + "even_minor": true, + "min_major": 4, + "prefixes": [ + "xfwm4-" + ] + }, + { + "id": "mate", + "name": "MATE desktop", + "repo": "mate-desktop/mate-desktop", + "baseline_tag": "v1.28.0", + "path": "schemas", + "focus": "Review appearance/schema changes. The baseline records the reviewed stable series, not a complete MATE login-session certification.", + "tests": "MATE appearance preference checks and GTK application smoke tests.", + "even_minor": true, + "min_major": 1, + "prefixes": [ + "", + "v" + ] + }, + { + "id": "marco", + "name": "Marco", + "repo": "mate-desktop/marco", + "baseline_tag": "v1.28.2", + "path": "src", + "focus": "Review Metacity decoration parsing, drawing and window states.", + "tests": "Native frame and Marco window-state tests.", + "even_minor": true, + "min_major": 1, + "prefixes": [ + "", + "v" + ] + }, + { + "id": "budgie", + "name": "Budgie", + "repo": "BuddiesOfBudgie/budgie-desktop", + "baseline_tag": "v10.10.3", + "path": "src", + "focus": "Review GTK integration and panel/Raven behavior. No dedicated Budgie shell stylesheet is supplied.", + "tests": "Appearance preference checks and panel/Raven smoke tests.", + "even_minor": false, + "min_major": 10, + "prefixes": [ + "", + "v" + ] + } + ] +} diff --git a/tests/test_upstream_watch.py b/tests/test_upstream_watch.py new file mode 100644 index 0000000..d28d262 --- /dev/null +++ b/tests/test_upstream_watch.py @@ -0,0 +1,122 @@ +"""Upstream discovery must not mistake development tags or API failures for stability.""" +import copy +import json +import os +from pathlib import Path +import sys +import subprocess +import tempfile +import unittest + +ROOT = Path(__file__).resolve().parents[1] +sys.path.insert(0, str(ROOT / 'tools')) +import upstream_watch as watch + + +def tag(name, sha='a' * 40): + return {'name': name, 'commit': {'sha': sha}} + + +class UpstreamWatchTests(unittest.TestCase): + def setUp(self): + self.catalog = watch.load_config(ROOT / 'maintenance/upstream-watch.json') + self.component = copy.deepcopy(self.catalog['components'][1]) + + def test_numeric_versions_and_development_filters(self): + c = self.component + data = [tag(t) for t in ('4.24.1', '4.24.10', '4.24.9', '4.25.1', '4.90.0', + '5.0.alpha', '5.0rc1', 'master.mint27', 'v3.22.20')] + self.assertEqual(watch.inspect_component(c, data)['latest'], '4.24.10') + data += [tag('5.0.0')] + self.assertEqual(watch.inspect_component(c, data)['latest'], '5.0.0') + gtk3 = self.catalog['components'][0] + self.assertEqual(watch.inspect_component(gtk3, data + [tag('3.24.52')])['latest'], '3.24.52') + shell = next(x for x in self.catalog['components'] if x['id'] == 'shell46') + self.assertEqual(watch.inspect_component(shell, [tag('46.10', shell['baseline_commit']), tag('51.1')])['latest'], '46.10') + + def test_complete_pagination_does_not_assume_api_order(self): + calls = [] + def fetch(repo, page): + calls.append(page) + return [tag('not-a-version-' + str(n)) for n in range(100)] if page == 1 else [tag('4.24.1'), tag('4.26.0')] + tags = watch.all_tags('GNOME/gtk', fetch) + self.assertEqual(calls, [1, 2]) + self.assertEqual(watch.inspect_component(self.component, tags)['latest'], '4.26.0') + with self.assertRaisesRegex(RuntimeError, 'incomplete'): + watch.all_tags('GNOME/gtk', lambda *_: [tag('4.24.1')] * 100, max_pages=2) + + def test_even_minor_rules_are_component_specific(self): + budgie = next(x for x in self.catalog['components'] if x['id'] == 'budgie') + self.assertEqual(watch.inspect_component(budgie, [tag('v10.10.3'), tag('v10.11.0')])['latest'], 'v10.11.0') + cinnamon = next(x for x in self.catalog['components'] if x['id'] == 'cinnamon') + self.assertEqual(watch.inspect_component(cinnamon, [tag('6.6.9'), tag('6.7.2'), tag('master.mint27')])['status'], 'no-new-tag') + xfce = next(x for x in self.catalog['components'] if x['id'] == 'xfce-panel') + tags = [tag(x) for x in ('xfce4-panel-4.20.8', 'xfce4-panel-4.21.2', 'xfce4-panel-4.22.0', 'xfce-4.24pre1')] + self.assertEqual(watch.inspect_component(xfce, tags)['latest'], 'xfce4-panel-4.22.0') + + def test_missing_baseline_and_repointed_pinned_tags_need_attention(self): + with self.assertRaisesRegex(ValueError, 'Baseline tag is absent'): + watch.inspect_component(self.component, [tag('4.26.0')]) + c = copy.deepcopy(self.component);c['baseline_commit'] = 'b' * 40 + r = watch.inspect_component(c, [tag('4.24.1')]) + self.assertTrue(r['baseline_commit_changed']) + self.assertEqual(r['status'], 'review-needed') + self.assertIn(c['baseline_commit'], r['compare_url']) + self.assertIn('different commit', watch.markdown({'checked_at': 'test', 'components': [r]})) + + def test_api_failure_is_partial_error_not_up_to_date_and_fetches_are_cached(self): + config = {'components': [self.component, self.catalog['components'][0], self.catalog['components'][2]]} + calls = [] + def fetch(repo, page): + calls.append((repo, page)) + if repo == 'GNOME/gtk':raise RuntimeError('API unavailable') + return [tag('1.10.0'), tag('1.12.0')] + report = watch.collect(config, fetch) + self.assertEqual(calls, [('GNOME/gtk', 1), ('GNOME/libadwaita', 1)]) + self.assertEqual(report['errors'], 2) + self.assertEqual(report['review_needed'], 1) + text = watch.markdown(report) + self.assertIn('Unavailable', text) + self.assertIn('not confirmed bugs', text) + self.assertIn('API unavailable', text) + + def test_config_rejects_duplicate_ids_invalid_repos_and_invalid_baselines(self): + for field, value in [('repo', '../unsafe'), ('baseline_tag', '4.25.0'), ('prefixes', [])]: + c = copy.deepcopy(self.component);c[field] = value + with tempfile.TemporaryDirectory() as tmp: + path = Path(tmp) / 'catalog.json';path.write_text(json.dumps({'version': 1, 'components': [c]})) + with self.assertRaises(ValueError):watch.load_config(path) + with tempfile.TemporaryDirectory() as tmp: + path = Path(tmp) / 'catalog.json' + path.write_text(json.dumps({'version': 1, 'components': [self.component, self.component]})) + with self.assertRaises(ValueError):watch.load_config(path) + + def test_cli_writes_summary_artifacts_and_fails_only_for_incomplete_checks(self): + with tempfile.TemporaryDirectory() as tmp: + root = Path(tmp) + config = root / 'config.json' + config.write_text(json.dumps({'version': 1, 'components': [self.component]})) + shim = root / 'gh' + env = dict(os.environ, PATH=str(root) + os.pathsep + os.environ['PATH'], + GITHUB_ACTIONS='true', GITHUB_STEP_SUMMARY=str(root / 'summary.md')) + command = [sys.executable, str(ROOT / 'tools/upstream_watch.py'), + '--config', str(config), '--output', str(root / 'report')] + for failure in (False, True): + shim.write_text('#!' + sys.executable + '\nimport sys,json\n' + + ('print("private tool diagnostic", file=sys.stderr);sys.exit(1)\n' if failure + else 'print(json.dumps(' + repr([tag('4.24.1'), tag('4.26.0')]) + '))\n')) + shim.chmod(0o755) + result = subprocess.run(command, env=env, capture_output=True, text=True, timeout=10) + self.assertEqual(result.returncode, 1 if failure else 0, result.stdout + result.stderr) + report = json.loads((root / 'report/report.json').read_text()) + self.assertEqual(report['errors'], 1 if failure else 0) + self.assertEqual(report['review_needed'], 0 if failure else 1) + self.assertIn('incomplete check' if failure else 'review-needed', + (root / 'report/report.md').read_text()) + self.assertNotIn('private tool diagnostic', (root / 'report/report.md').read_text()) + self.assertTrue((root / 'summary.md').is_file()) + if not failure:self.assertIn('::warning', result.stdout) + + +if __name__ == '__main__': + unittest.main(verbosity=2) diff --git a/tools/upstream_watch.py b/tools/upstream_watch.py new file mode 100644 index 0000000..53696b1 --- /dev/null +++ b/tools/upstream_watch.py @@ -0,0 +1,167 @@ +#!/usr/bin/env python3 +"""Read-only upstream tag watch. Reports review candidates, never compatibility.""" +import argparse +from datetime import datetime, timezone +import json +import os +from pathlib import Path +import re +import subprocess +from urllib.parse import quote + +ROOT = Path(__file__).resolve().parents[1] + + +def version(tag, prefixes): + for prefix in prefixes: + if tag.startswith(prefix): + text = tag[len(prefix):] + if re.fullmatch(r'\d+\.\d+(?:\.\d+)?', text): + return tuple(map(int, text.split('.'))) + (0,) * (3 - len(text.split('.'))) + return None + + +def eligible(number, component): + return (number is not None and number[0] >= component['min_major'] + and (component.get('max_major') is None or number[0] <= component['max_major']) + and number[1] < 90 + and (not component['even_minor'] or number[1] % 2 == 0)) + + +def load_config(path): + config = json.loads(path.read_text()) + if config.get('version') != 1 or not isinstance(config.get('components'), list) or not config['components']: + raise ValueError('Expected nonempty version 1 component catalog') + seen = set() + for c in config['components']: + if not re.fullmatch(r'[a-z0-9-]+', c['id']) or c['id'] in seen: + raise ValueError('Invalid or duplicate component identity') + seen.add(c['id']) + if (not re.fullmatch(r'[A-Za-z0-9][A-Za-z0-9-]*/[A-Za-z0-9_.-]+', c['repo']) + or c['repo'].split('/')[-1] in ('.', '..')): + raise ValueError('Invalid repository') + if not c['prefixes'] or not all(isinstance(p, str) for p in c['prefixes']): + raise ValueError('Expected explicit tag prefixes') + baseline = version(c['baseline_tag'], c['prefixes']) + if not isinstance(c['even_minor'], bool) or not eligible(baseline, c): + raise ValueError('Baseline does not match component stable-tag rules') + if 'baseline_commit' in c and not re.fullmatch(r'[0-9a-f]{40}', c['baseline_commit']): + raise ValueError('Invalid baseline commit') + return config + + +def api_tags(repo, page): + result = subprocess.run(['gh', 'api', f'repos/{repo}/tags?per_page=100&page={page}'], + capture_output=True, text=True, timeout=45) + if result.returncode: + # Do not echo credential/tool diagnostics into public reports. + raise RuntimeError(f'GitHub tag request failed for {repo}, page {page}; check API access/rate limits') + data = json.loads(result.stdout) + if not isinstance(data, list) or any(not isinstance(t, dict) or not isinstance(t.get('name'), str) + or not isinstance(t.get('commit', {}).get('sha'), str) for t in data): + raise ValueError('Unexpected GitHub tags response') + return data + + +def all_tags(repo, fetch=api_tags, max_pages=50): + tags = [] + for page in range(1, max_pages + 1): + batch = fetch(repo, page) + tags.extend(batch) + if len(batch) < 100: + return tags + raise RuntimeError(f'Tag pagination limit reached for {repo}; report is incomplete') + + +def inspect_component(component, tags): + c = component + baseline = version(c['baseline_tag'], c['prefixes']) + by_name = {t['name']: t for t in tags} + if c['baseline_tag'] not in by_name: + raise ValueError('Baseline tag is absent upstream; review catalog/mirror before concluding anything') + candidates = [(version(t['name'], c['prefixes']), t['name'], t['commit']['sha']) for t in tags] + candidates = [t for t in candidates if eligible(t[0], c)] + if not candidates: + raise ValueError('No matching stable-looking numeric tags found') + latest, tag, commit = max(candidates) + moved = bool(c.get('baseline_commit') and by_name[c['baseline_tag']]['commit']['sha'] != c['baseline_commit']) + comparison_base = c['baseline_commit'] if moved else c['baseline_tag'] + return {'id': c['id'], 'name': c['name'], 'repo': c['repo'], 'baseline': c['baseline_tag'], + 'latest': tag, 'latest_commit': commit, + 'status': 'review-needed' if latest > baseline or moved else 'no-new-tag', + 'baseline_commit_changed': moved, 'focus': c['focus'], 'tests': c['tests'], + 'source_url': f"https://github.com/{c['repo']}/tree/{quote(tag, safe='')}/{c['path']}", + 'compare_url': f"https://github.com/{c['repo']}/compare/{quote(comparison_base, safe='')}...{quote(tag, safe='')}"} + + +def collect(config, fetch=api_tags): + cache = {} + rows = [] + for c in config['components']: + try: + if c['repo'] not in cache: + try: + cache[c['repo']] = all_tags(c['repo'], fetch) + except (RuntimeError, ValueError, OSError, subprocess.TimeoutExpired) as error: + cache[c['repo']] = error + if isinstance(cache[c['repo']], Exception): + raise cache[c['repo']] + rows.append(inspect_component(c, cache[c['repo']])) + except (RuntimeError, ValueError, OSError, subprocess.TimeoutExpired) as error: + rows.append({'id': c['id'], 'name': c['name'], 'repo': c['repo'], + 'baseline': c['baseline_tag'], 'status': 'error', 'error': str(error)}) + return {'checked_at': datetime.now(timezone.utc).isoformat(), 'components': rows, + 'review_needed': sum(r['status'] == 'review-needed' for r in rows), + 'errors': sum(r['status'] == 'error' for r in rows)} + + +def markdown(report): + lines = ['# Upstream review watch', '', f"Checked: {report['checked_at']}", '', + '**New tags are review candidates, not confirmed bugs or compatibility results.**', '', + '| Component | Review baseline | Latest matching tag | Result |', + '| --- | --- | --- | --- |'] + for r in report['components']: + latest = f"[{r['latest']}]({r['source_url']})" if r['status'] != 'error' else 'Unavailable' + lines.append(f"| {r['name']} | `{r['baseline']}` | {latest} | {r['status']} |") + for r in report['components']: + if r['status'] == 'error': + lines += ['', f"## {r['name']}: incomplete check", '', r['error']] + elif r['status'] == 'review-needed': + lines += ['', f"## {r['name']}: review needed", '', f"[Upstream changes]({r['compare_url']}) · [Source]({r['source_url']})", '', + r['focus'], '', 'Suggested validation: ' + r['tests']] + if r['baseline_commit_changed']: + lines += ['', '**The pinned baseline tag now points to a different commit. Investigate before importing it.**'] + lines += ['', '## Next steps', '', + 'Review upstream NEWS and relevant style/widget changes. Reproduce any suspected regression,', + 'fix confirmed problems, then run the affected native tests. Update the catalog baseline only', + 'after recording what was reviewed/tested in COMPATIBILITY.md; keep unsupported versions explicit.', '', + 'No-new-tag means this tag check found no newer matching release candidate. It does not prove', + 'bug-free operation or detect unreleased branch changes. GitHub mirrors may lag primary upstreams.', + 'Development suffixes, odd development minors where configured, and minor versions ≥90 are excluded.', ''] + return '\n'.join(lines) + + +def main(): + parser = argparse.ArgumentParser(description=__doc__) + parser.add_argument('--config', type=Path, default=ROOT / 'maintenance/upstream-watch.json') + parser.add_argument('--output', type=Path, default=ROOT / 'upstream-report') + args = parser.parse_args() + config = load_config(args.config) + report = collect(config) + args.output.mkdir(parents=True, exist_ok=True) + (args.output / 'report.json').write_text(json.dumps(report, indent=2) + '\n') + content = markdown(report) + (args.output / 'report.md').write_text(content) + if os.environ.get('GITHUB_STEP_SUMMARY'): + with open(os.environ['GITHUB_STEP_SUMMARY'], 'a') as stream: + stream.write(content) + print(f"Upstream watch: {report['review_needed']} review candidates; {report['errors']} incomplete checks.") + if os.environ.get('GITHUB_ACTIONS') == 'true': + for row in report['components']: + if row['status'] == 'review-needed': + print(f"::warning title=Upstream review needed::{row['id']}: {row['baseline']} -> {row['latest']}; see run summary") + return 1 if report['errors'] else 0 + + +if __name__ == '__main__': + raise SystemExit(main())