Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
43 changes: 43 additions & 0 deletions .github/workflows/upstream-watch.yml
Original file line number Diff line number Diff line change
@@ -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
7 changes: 7 additions & 0 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -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`.
1 change: 1 addition & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand Down
74 changes: 74 additions & 0 deletions maintenance/README.md
Original file line number Diff line number Diff line change
@@ -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.
202 changes: 202 additions & 0 deletions maintenance/upstream-watch.json
Original file line number Diff line number Diff line change
@@ -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"
]
}
]
}
Loading
Loading