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​

Running the test suite requires PyGObject and GTK 4/Libadwaita development bindings installed on the host system:

python3 -m pytest tests/                                       # full suite
python3 -m pytest tests/test_backend.py -v                     # one file
python3 -m pytest tests/test_benchmarks.py --benchmark-enable  # benchmarks

Tests run headlessly — the autouse fixtures in tests/conftest.py mock Gio.Settings and dialog .present() calls so nothing pops on screen. If you add new dialog types, extend that fixture.

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 python3 -m pytest tests/ locally before opening.
  • 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​