Skip to main content

Contributing

Thanks for wanting to help! Tavern is a GTK 4 / Libadwaita Homebrew client written in Python with Blueprint UI definitions.

Dev setup​

Install build dependencies (Homebrew on Linux or macOS):

brew install gtk4 libadwaita meson ninja pygobject3 gettext desktop-file-utils blueprint-compiler

Build, install to ~/.local, and launch:

./run.sh                  # normal run
TAVERN_LOG=debug ./run.sh # with verbose logging

For a sandboxed Flatpak build (requires just):

just dev                  # build + install + run as Flatpak

Tests​

Use the system Python with its PyGObject bindings. A separate Python install such as actions/setup-python cannot use the distribution's python3-gi. On Ubuntu, install the same dependencies as CI:

sudo apt-get update
sudo apt-get install -y python3-gi python3-gi-cairo python3-pip \
  gir1.2-gtk-4.0 gir1.2-adw-1 gir1.2-gdkpixbuf-2.0 \
  libglib2.0-dev-bin libxml2-utils blueprint-compiler xvfb dbus-x11
/usr/bin/python3 -m pip install --break-system-packages pytest pytest-benchmark

Build the UI resource at the exact path that tests/conftest.py loads:

mkdir -p build-ui .flatpak-build/files/share/tavern
blueprint-compiler batch-compile build-ui src src/*.blp
cp src/style.css build-ui/
glib-compile-resources \
  --target=.flatpak-build/files/share/tavern/tavern.gresource \
  --sourcedir=build-ui --sourcedir=src src/tavern.gresource.xml

xvfb-run -a dbus-run-session -- /usr/bin/python3 -m pytest tests/ -m "not slow"
/usr/bin/python3 -m pytest tools/tests/

Use a file path in place of tests/ to run one file. Add --benchmark-enable to run benchmarks. The benchmark plugin is required even when benchmarks are off. GTK needs a display and session bus; the fixtures alone do not provide these. The host job may skip tests that need Adw.Spinner (libadwaita 1.6 or later). Both the host and GNOME 50 Flatpak test jobs must pass before merge. Use just dev for the separate Flatpak development path.

Working on the UI​

Blueprint files (.blp) compile to .ui XML at build time via blueprint-compiler. Always rebuild after editing a .blp:

./run.sh                  # re-runs blueprint-compiler

When adding a new page, keep Blueprint, Python, window wiring, gresource registration, and meson sources in sync — the repo layout in README.md and src/ shows where each piece lands.

Localization​

Wrap every user-visible Blueprint value in _(), for example label: _("Install");, and add new Blueprint/Python sources to po/POTFILES.in. Python UI strings should use gettext.gettext (_) or ngettext for plurals. Before opening a PR, run:

python3 tools/check-translations.py
meson setup build
meson compile -C build tavern-pot

Add a locale code to po/LINGUAS only when its .po catalog is ready to ship. Translation-only PRs are welcome and do not require changes to Python.

Additional maintainer guides cover the cache lifecycle, curation feed, accessibility release pass, and release process.

The files under docs/reports/ are dated historical verification snapshots, not maintained contributor instructions.

Pull requests​

  • Keep PRs focused — one change, one PR.
  • Include a screenshot or short clip for any user-visible UI change.
  • Run the test commands above before you open a PR.
  • Reference the issue you're closing (Closes #123).

Code style​

  • Match the surrounding style — Tavern is a small codebase, consistency matters more than any specific rule.
  • Logging is off by default. New code should use _log = get_logger('module_name') from logging_util, not bare print.
  • Backend I/O goes on a thread and reports back via GLib.idle_add — don't block the UI thread.

Project docs​

Contribute compute — no code needed​

No time to write code? You can still push this project's backlog forward. TunaOS AI-agent hives work on this repository. Lend a hive your AI subscription or API tokens, and your machine runs contributor tasks from this project's backlog.