Skip to content
Flatpak Automatic CLI Banner

Development Notes

This document outlines the development and deployment workflows for the Flatpak Automatic project.

Building the RPM

To build the RPM package:

make rpm

Customizing at Build Time

You can override variables during the RPM build:

rpmbuild -ba rpm/flatpak-automatic.spec --define "OPEN_WEBUI_PORT 8080"

GitOps PR CLI Tool

The project includes a scripts/maintainer/gitops-pr-cli-tool.sh to automate and enforce the Pull Request workflow. It performs the following checks:

  • Branch Naming Validation: Ensures conformity to the <type>/v<version>-<description> standard.
  • Conventional Commits Check: Verifies that the branch commit history uses valid Conventional Commit prefixes so that tbump can generate an accurate changelog upon release.
  • Packaging Skeleton Verification: Ensures required RPM and Debian template files exist.
  • Automatic PR Formatting: Generates the PR title and body dynamically from the commit history.

Prerequisites

  • GitHub CLI (gh): The tool requires the GitHub CLI to be installed and authenticated.

Usage:

./scripts/maintainer/gitops-pr-cli-tool.sh --target <branch-name> \
  [--base main] \
  [--title "PR Title"] \
  [--message "PR Body"] \
  [--reviewers user1,user2] \
  [--remote origin] \
  [--dry-run]

Git Clean & Switch Tool

A scripts/maintainer/git-clean-switch-tool.sh is provided to safely reset the current Git branch to a remote source, clean the worktree, and prepare a development branch. This is useful for quickly synchronizing a development environment to a known good state.

Usage:

./scripts/maintainer/git-clean-switch-tool.sh \
  [--base main] \
  [--target dev] \
  [--backup backup-main-timestamp] \
  [--remote origin] \
  [--dry-run]

Testing Matrix

This project enforces a Shift-Left testing approach.

  • Config Validation: Always run flatpak-automatic --check-config after modifying default YAML templates.
  • Integration Tests: Execute tests/integration_test_dbus.py for DBus validation.
  • Notification Tests: Execute tests/test_notifications.py for UI/UX alerting validation.
  • Live Notification Testing: Use flatpak-automatic --test-notify to validate the entire dispatch pipeline.
  • Automation: The GitOps patcher logic ensures test coverage is maintained on all PRs.

Troubleshooting for Developers

  • D-Bus Timeouts: If the dry-run check fails silently, ensure the user has permission to talk to the Flatpak system/session bus.
  • Path Issues: In development, the script automatically prioritizes local config/ and src/ directories. If it's picking up system-wide files, ensure you are running from the project root.
  • State Corruption: If --status shows incorrect data, you can safely delete /var/lib/flatpak-automatic/state.json (root) or ~/.local/state/flatpak-automatic/state.json (user) to reset it.
  • Log Verbosity: The default logging level is INFO. For deep debugging, modify src/flatpak_automatic/logging_utils.py or use DEBUG=1 if implemented (currently requires code modification).

Architectural Standards & Feature Parity

  • Non-Root Execution: All new features MUST maintain strict compatibility with user-level systemd units. Privilege escalation is explicitly forbidden unless structurally required by the underlying Flatpak API.