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
76 changes: 76 additions & 0 deletions .github/ISSUE_TEMPLATE/bug-report.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,76 @@
name: Report a theme or installer problem
description: Help reproduce a visual, application, icon or installation problem.
title: '[Bug]: '
body:
- type: dropdown
id: area
attributes:
label: Which part is affected?
options:
- GTK application styling
- GNOME Shell
- Cinnamon desktop / panel / menu
- Window decorations or another desktop
- Folder icons
- Qt or application extras
- Installer / update / removal
- Other / unsure
validations:
required: true
- type: textarea
id: environment
attributes:
label: Versions and environment
description: Unknown versions are fine—include what you know.
value: |
Distribution and version:
Desktop and version:
Theme version (release or commit):
Theme accent / folder color:
Application and version (or install.sh):
X11 or Wayland, if known:
validations:
required: true
- type: dropdown
id: installation
attributes:
label: How was the theme installed?
options:
- Guided installer from a release download
- Installer with command-line options
- Installer from a Git checkout
- Manual installation
- Other / unsure
validations:
required: true
- type: textarea
id: steps
attributes:
label: Steps to reproduce
description: Include the installer command/options if relevant.
placeholder: '1. Open the application…'
validations:
required: true
- type: textarea
id: expected
attributes:
label: What did you expect?
validations:
required: true
- type: textarea
id: actual
attributes:
label: What happened instead?
description: Paste the exact error if there is one.
validations:
required: true
- type: textarea
id: screenshots
attributes:
label: Screenshots
description: Drag images here for visual problems. Include the affected widget and surrounding window.
- type: textarea
id: details
attributes:
label: Relevant logs or customizations (optional)
description: Mention extensions, other GTK overrides or Flatpak packaging if relevant. Include only relevant logs; do not paste secrets or a full environment dump.
5 changes: 5 additions & 0 deletions .github/ISSUE_TEMPLATE/config.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
blank_issues_enabled: true
contact_links:
- name: Installation and application setup
url: https://github.com/librerob/adwaita-amoled/blob/main/INSTALLING.md
about: Destinations, manual alternatives, GTK4, Flatpak and application-specific instructions.
13 changes: 13 additions & 0 deletions .github/dependabot.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,13 @@
version: 2
updates:
- package-ecosystem: github-actions
directory: /
schedule:
interval: monthly
time: '09:30'
timezone: Europe/London
open-pull-requests-limit: 3
groups:
github-actions:
patterns:
- '*'
54 changes: 54 additions & 0 deletions .github/workflows/release-verification.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,54 @@
name: Release verification

on:
release:
types: [published]
workflow_dispatch:
inputs:
tag:
description: 'Release tag (leave blank for the latest stable release)'
required: false
type: string
pull_request:
paths:
- '.github/workflows/release-verification.yml'
- 'tools/verify_release.py'
- 'tools/package.py'
- 'tests/test_release_verification.py'
push:
branches: [main]
paths:
- '.github/workflows/release-verification.yml'
- 'tools/verify_release.py'
- 'tools/package.py'
- 'tests/test_release_verification.py'

permissions:
contents: read

jobs:
verify:
if: github.event_name != 'release' || !github.event.release.prerelease
runs-on: ubuntu-24.04
timeout-minutes: 10
steps:
- uses: actions/checkout@v7
with:
ref: ${{ github.event_name == 'pull_request' && github.ref || github.event.repository.default_branch }}
fetch-depth: 0
persist-credentials: false
- name: Test archive integrity and unsafe-input rejection
run: python3 tests/test_release_verification.py
- name: Verify published archive against its tag
env:
GH_TOKEN: ${{ github.token }}
RELEASE_TAG: ${{ github.event.release.tag_name || inputs.tag }}
run: python3 tools/verify_release.py --tag "$RELEASE_TAG" --output '${{ runner.temp }}/release-verification'
- name: Save verification report
if: always()
uses: actions/upload-artifact@v7
with:
name: release-verification-report
path: ${{ runner.temp }}/release-verification
retention-days: 90
if-no-files-found: warn
21 changes: 21 additions & 0 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -86,3 +86,24 @@ 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`.

## Release integrity

After publishing a stable release with its runtime archive attached, check the
[Release verification workflow](https://github.com/librerob/adwaita-amoled/actions/workflows/release-verification.yml).
Use **Run workflow** to verify an older release or an asset uploaded after
publication. Verification is read-only; it does not publish releases.

For local development, use Python 3.11+, authenticated GitHub CLI and a checkout
with the requested release tag fetched:

```bash
python3 tests/test_release_verification.py
git fetch origin tag v1.9.0
python3 tools/verify_release.py --tag v1.9.0 --output /tmp/adwaita-release-report
```

The verifier uses this checkout's packager with tagged source as data. Preserve
compatibility with existing archives when changing the packaging format, or
extend verification deliberately. See [maintenance guidance](maintenance/README.md#other-repository-maintenance)
for report details and the other repository automation.
2 changes: 1 addition & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -173,6 +173,6 @@ for tested versions and coverage limits.

## Feedback

[Report a problem or contribute](https://github.com/librerob/adwaita-amoled/issues).
[Report a problem](https://github.com/librerob/adwaita-amoled/issues/new?template=bug-report.yml) or [contribute](CONTRIBUTING.md).
Include your distribution, desktop/version, application, selected accent and
theme version so the problem can be reproduced.
33 changes: 33 additions & 0 deletions maintenance/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -86,3 +86,36 @@ 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.

## Other repository maintenance

Dependabot checks GitHub Actions dependencies monthly and groups updates into
one pull request. Review the changes and passing checks before merging; automatic
merging is not configured. This does not update theme imports or palettes.

The [bug-report form](https://github.com/librerob/adwaita-amoled/issues/new?template=bug-report.yml)
asks for the desktop, theme version, accent, installation method and reproduction
steps, with space for screenshots. Blank issues remain available.

Secret scanning and push protection are managed in repository **Settings →
Advanced Security / Secret protection**. Keep both enabled. They detect supported
credential patterns; they do not establish that code or an installer is safe.

[Release verification](https://github.com/librerob/adwaita-amoled/actions/workflows/release-verification.yml)
runs when a stable release is published, and when its verification code changes.
To check an existing release, choose **Run workflow**, select `main` and enter
its tag, or leave the tag blank for the latest stable release.

The verifier downloads the uploaded `Adwaita-AMOLED-vX.Y.Z.tar.gz`, rebuilds the
runtime archive from that tag's data using the current trusted packager, and
requires a byte-for-byte match. It also checks the archive's file checksums and
the included accent/icon checksum manifests. It never runs build scripts or the
installer from the release tag. A packaging-format change may require updating
the verifier to retain compatibility with older archives.

Open the run's **Summary** for the result, commit, tree and archive SHA-256.
The **release-verification-report** artifact retains Markdown and JSON reports
for 90 days. Missing, corrupted or mismatched assets fail verification. This
checks release integrity, not application rendering or desktop compatibility.
It does not publish, repair or modify a release. If assets are uploaded after
publication or replaced later, run verification again manually.
117 changes: 117 additions & 0 deletions tests/test_release_verification.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,117 @@
"""Published archives must match tag data; no tagged build code may execute."""
import contextlib
import io
from pathlib import Path
import shutil
import subprocess
import sys
import tempfile
import tarfile
import unittest

ROOT = Path(__file__).resolve().parents[1]
sys.path.insert(0, str(ROOT / 'tools'))
import package as packaging
import verify_release as verifier


def git(root, *args):
return subprocess.check_output(['git', '-c', 'user.name=Release verifier test',
'-c', 'user.email=test@example.invalid', '-c', 'commit.gpgsign=false',
'-c', 'core.hooksPath=/dev/null', *args], cwd=root, stderr=subprocess.DEVNULL)


def build(root, target):
before_root, before_argv = packaging.ROOT, sys.argv
try:
packaging.ROOT = root;sys.argv = ['package.py', str(target)]
with contextlib.redirect_stdout(io.StringIO()):packaging.main()
finally:
packaging.ROOT, sys.argv = before_root, before_argv


class ReleaseVerificationTests(unittest.TestCase):
@classmethod
def setUpClass(cls):
cls.temporary = tempfile.TemporaryDirectory(prefix='amoled-verifier-tests-')
cls.base = Path(cls.temporary.name);cls.source = cls.base / 'original';cls.source.mkdir()
for name in packaging.runtime_paths(ROOT) + packaging.accent_paths(ROOT):
target = cls.source / name;target.parent.mkdir(parents=True, exist_ok=True)
shutil.copy2(ROOT / name, target)
# A tagged script is deliberately hostile. The verifier must only use
# the current trusted packager, treating the tag's files as inert data.
(cls.source / 'tools').mkdir()
(cls.source / 'tools/package.py').write_text('raise RuntimeError("TAG CODE EXECUTED")\n')
git(cls.source, 'init', '-q');git(cls.source, 'add', '.')
git(cls.source, 'commit', '-qm', 'fixture')
git(cls.source, 'tag', 'v99.0.0')
git(cls.source, 'tag', '-a', 'v99.0.1', '-m', 'Annotated fixture')
cls.archive = cls.base / 'original.tar.gz';build(cls.source, cls.archive)

@classmethod
def tearDownClass(cls):cls.temporary.cleanup()

def setUp(self):
self.work = Path(tempfile.mkdtemp(dir=self.base))
self.addCleanup(shutil.rmtree, self.work)

def clone(self):
root = self.work / 'repository'
git(self.base, 'clone', '-q', '--local', str(self.source), str(root))
return root

def verify(self, root, tag='v99.0.0', archive=None):
with contextlib.redirect_stdout(io.StringIO()):
return verifier.verify_archive(root, tag, archive or self.archive)

def test_exact_archive_and_lightweight_or_annotated_tag_pass_without_tag_code(self):
for tag in ('v99.0.0', 'v99.0.1'):
report = self.verify(self.source, tag)
self.assertEqual(report['source_match'], 'byte-for-byte')
self.assertFalse(report['tag_code_executed'])
self.assertGreater(report['checksum_entries'], report['files'])
self.assertEqual(report['commit'], git(self.source, 'rev-parse', 'HEAD').decode().strip())

def test_corrupt_or_missing_archive_fails(self):
damaged = self.work / 'bad.tar.gz';data = bytearray(self.archive.read_bytes());data[-1] ^= 1
damaged.write_bytes(data)
with self.assertRaisesRegex(ValueError, 'differs from tagged source'):
self.verify(self.source, archive=damaged)
with self.assertRaises(FileNotFoundError):self.verify(self.source, archive=self.work / 'absent.tar.gz')

def test_archive_from_different_source_commit_fails(self):
root = self.clone();(root / 'README.md').write_text('Different release source\n')
git(root, 'add', 'README.md');git(root, 'commit', '-qm', 'change')
git(root, 'tag', 'v99.0.2')
with self.assertRaisesRegex(ValueError, 'differs from tagged source'):
self.verify(root, 'v99.0.2')

def test_unknown_or_unsafe_tags_fail(self):
for name in ('main', '../../elsewhere', '--help', 'v99.0.0;echo nope'):
with self.assertRaisesRegex(ValueError, 'stable tag'):self.verify(self.source, name)
with self.assertRaisesRegex(ValueError, 'Command failed'):self.verify(self.source, 'v99.9.9')

def test_self_consistent_package_with_bad_internal_icon_manifest_fails(self):
root = self.clone();manifest = root / 'extra/icons/Adwaita-AMOLED/SHA256SUMS'
text = manifest.read_text();manifest.write_text('0' * 64 + text[64:])
git(root, 'add', '.');git(root, 'commit', '-qm', 'bad internal checksum');git(root, 'tag', 'v99.0.2')
archive = self.work / 'bad-manifest.tar.gz';build(root, archive)
with self.assertRaisesRegex(ValueError, 'Checksum mismatch'):self.verify(root, 'v99.0.2', archive)

def test_invalid_checksum_paths_and_duplicate_entries_are_rejected(self):
digest = '0' * 64
for text in (digest + ' ../escape\n', digest + ' /absolute\n',
digest + ' ok\n' + digest + ' ok\n', ''):
with self.assertRaises(ValueError):verifier.verify_manifest(text.encode(), lambda _: b'content')

def test_runtime_symlink_is_rejected_without_reading_its_target(self):
root = self.clone();readme = root / 'README.md';readme.unlink()
target = self.work / 'private.txt';target.write_text('untouched')
readme.symlink_to(target)
git(root, 'add', '.');git(root, 'commit', '-qm', 'linked payload');git(root, 'tag', 'v99.0.2')
with self.assertRaises((ValueError, SystemExit, tarfile.FilterError)):
self.verify(root, 'v99.0.2')
self.assertEqual(target.read_text(), 'untouched')


if __name__ == '__main__':unittest.main(verbosity=2)
Loading
Loading