Jeena
501a84e0a9
Update project metadata, docs, and systemd unit names to match the new service-update-alerts naming.
154 lines
6.5 KiB
Markdown
154 lines
6.5 KiB
Markdown
# Backlog: service-update-alerts
|
|
|
|
## US-01 - Curated Webservice Dataset
|
|
|
|
As a maintainer, I want a curated YAML dataset of webservices to check so that the script does not rely on scraping a status page.
|
|
|
|
Acceptance criteria:
|
|
- A YAML file contains the full list of webservices (name + base URL).
|
|
- Each entry supports version endpoint and upstream metadata fields, even if left empty initially.
|
|
- The script can load the dataset without performing any network discovery.
|
|
|
|
## US-01A - Sample Environment File
|
|
|
|
As a maintainer, I want a `.env.sample` file listing required authentication variables so that I can configure the script quickly.
|
|
|
|
Acceptance criteria:
|
|
- `.env.sample` exists and lists required auth environment variables.
|
|
- Each variable includes a short note about its expected format.
|
|
- Optional variables are clearly marked.
|
|
|
|
## US-02 - Service Research Dataset
|
|
|
|
As a maintainer, I want to research and populate version endpoints and upstream release sources for each webservice so that checks are reliable without guesswork.
|
|
|
|
Acceptance criteria:
|
|
- Each webservice entry includes `current_version_url` and `upstream_latest_version_url`.
|
|
- Each entry includes extraction rules for both current and latest versions.
|
|
- Services without a viable version endpoint are clearly marked with notes and `current_version_url` left empty.
|
|
|
|
## US-03 - Dataset Loader and Validation
|
|
|
|
As a maintainer, I want to load and validate the curated dataset so that the script can operate consistently on structured inputs.
|
|
|
|
Acceptance criteria:
|
|
- The script accepts a `--config` CLI argument and reads a YAML file.
|
|
- The dataset is validated for required fields and data types.
|
|
- Invalid datasets are rejected with a clear error message.
|
|
|
|
## US-04 - Version Fetching and Parsing
|
|
|
|
As a maintainer, I want to fetch versions using dataset-defined endpoints and extraction rules so that version detection is consistent across services.
|
|
|
|
Acceptance criteria:
|
|
- The script fetches `current_version_url` for each service.
|
|
- The script applies the dataset extraction rule to obtain the running version.
|
|
- Failures are logged per service without aborting the run.
|
|
|
|
## US-05 - Upstream Release Lookup
|
|
|
|
As a maintainer, I want to query upstream release APIs (GitHub and Codeberg) so that I can compare current and latest versions.
|
|
|
|
Acceptance criteria:
|
|
- The script can fetch the latest release for GitHub repositories.
|
|
- The script can fetch the latest release for Codeberg repositories.
|
|
- If no releases are available, the script can fall back to the latest tag.
|
|
|
|
## US-06 - Version Normalization and Comparison
|
|
|
|
As a maintainer, I want version strings normalized and compared consistently so that update checks are accurate.
|
|
|
|
Acceptance criteria:
|
|
- Versions are normalized to handle leading "v" and common tag formats.
|
|
- Semantic versions are compared using a proper parser.
|
|
- Unparseable versions are flagged and still reported.
|
|
|
|
## US-07 - Update Report Output
|
|
|
|
As a maintainer, I want the script to print only services with updates by default, and optionally all services, so that I can focus on actionable results.
|
|
|
|
Acceptance criteria:
|
|
- Default output includes only services where latest > running.
|
|
- `--all` prints all services including up-to-date and unknown versions.
|
|
- Output includes service name, running version, latest version, and upstream URL.
|
|
|
|
## US-08 - CLI and Runtime Options
|
|
|
|
As a maintainer, I want a simple CLI with timeouts and user-agent settings so that the script works reliably in different environments.
|
|
|
|
Acceptance criteria:
|
|
- The script supports `--timeout` and `--user-agent` flags.
|
|
- Defaults are documented in `--help` output.
|
|
- Invalid arguments produce a helpful error message.
|
|
|
|
## US-09 - Resilience and Errors
|
|
|
|
As a maintainer, I want network failures and API errors handled gracefully so that one bad service does not break the whole run.
|
|
|
|
Acceptance criteria:
|
|
- Network timeouts and HTTP errors are logged per service.
|
|
- The script continues processing remaining services after a failure.
|
|
- The final exit code is non-zero only for total failure (e.g., cannot fetch service list).
|
|
|
|
## US-10 - Output Formatting and Exit Codes
|
|
|
|
As a maintainer, I want consistent output formatting and exit codes so that this script can be used in cron jobs or CI.
|
|
|
|
Acceptance criteria:
|
|
- The script exits with code 0 when it completes a run.
|
|
- The script exits with code 1 on unrecoverable setup failures.
|
|
- Output is stable across runs for the same inputs.
|
|
|
|
## US-11 - Automated Tests
|
|
|
|
As a maintainer, I want tests for extraction and version comparison so that changes can be verified quickly.
|
|
|
|
Acceptance criteria:
|
|
- Tests cover JSONPath, regex, and header extraction.
|
|
- Tests cover version comparison including prerelease handling.
|
|
- Tests run with pytest.
|
|
|
|
## US-12 - Python Project Setup
|
|
|
|
As a maintainer, I want a virtual environment workflow with `pyproject.toml` so that dependencies are managed consistently.
|
|
|
|
Acceptance criteria:
|
|
- `pyproject.toml` defines runtime and dev dependencies.
|
|
- README documents venv setup and installation commands.
|
|
- `.venv` is ignored by git.
|
|
|
|
## US-13 - FreshRSS Authenticated Version Check
|
|
|
|
As a maintainer, I want FreshRSS version detection to authenticate with a username and password so that the script can read the About page and extract the running version.
|
|
|
|
Acceptance criteria:
|
|
- The script can log in to FreshRSS using credentials from environment variables.
|
|
- FreshRSS version is extracted from the About page after authentication.
|
|
- `.env.sample` documents the FreshRSS credentials required.
|
|
|
|
## US-14 - Matrix Notifications
|
|
|
|
As a maintainer, I want the script to post update alerts to a Matrix room so that I can track service changes and failures without email.
|
|
|
|
Acceptance criteria:
|
|
- The script posts a message to a Matrix room when updates are detected or errors occur.
|
|
- Matrix credentials (homeserver, room id, access token) are read from `.env`.
|
|
- The message includes actionable service names and version details.
|
|
|
|
## US-15 - Systemd User Service
|
|
|
|
As a maintainer, I want a systemd user service and timer so the script runs daily without manual intervention.
|
|
|
|
Acceptance criteria:
|
|
- Provide a user-level systemd service file that runs the update checker.
|
|
- Provide a user-level timer that runs once per day.
|
|
- README documents how to install and enable the service and timer.
|
|
|
|
## US-16 - Uptime Kuma Push
|
|
|
|
As a maintainer, I want the script to call an Uptime Kuma push URL on each run so that failures are visible in the monitoring dashboard.
|
|
|
|
Acceptance criteria:
|
|
- The script sends a request to the push URL when it runs.
|
|
- The push URL is configured via `.env`.
|
|
- Failures to reach the push URL are logged without crashing the run.
|