1

Development

Pavel Baksy edited this page 2026-01-13 17:08:01 +01:00

Table of Contents

• Development
• Development Environment
• Prerequisites
• Clone Repository
• Building
• Native Build
• Run Without Installing
• Install Locally
• Flatpak Build
• Project Structure
• Development Workflow
• Making Changes
• UI Changes
• Adding Python Modules
• Schema Changes
• Testing
• Run Tests
• Manual Testing
• Debugging
• Python Debugging
• GTK Inspector
• Flatpak Debugging
• Logs
• Code Style
• Next Steps

Development

Developer guide for working on Roster.

Development Environment

Prerequisites

Install build dependencies (see Installation):

• Meson, Ninja
• GTK 4, libadwaita development files
• Python 3, PyGObject
• GJS for script testing

Clone Repository

git clone https://git.bugsy.cz/beval/roster.git
cd roster

Building

Native Build

meson setup builddir
meson compile -C builddir

Run Without Installing

meson devenv -C builddir
python3 src/main.py

Install Locally

meson install -C builddir --destdir /tmp/roster-install

Flatpak Build

Recommended for testing sandboxed environment:

flatpak-builder --user --install --force-clean build-dir cz.bugsy.roster.json
flatpak run cz.bugsy.roster

Project Structure

roster/
├── data/              # Desktop files, icons, schemas
├── po/                # Translations
├── src/               # Python source code
│   ├── main.py        # Application entry point
│   ├── window.py      # Main window class
│   ├── window.ui      # UI definition
│   └── ...
└── meson.build        # Build configuration

See Architecture for detailed technical overview.

Development Workflow

Making Changes

1. Create feature branch
2. Edit source files in src/
3. Rebuild: meson compile -C builddir
4. Test changes
5. Commit with descriptive message

UI Changes

UI files are in src/*.ui (GTK Builder XML format).

After editing .ui files:

1. Rebuild to update GResources
2. Test with meson devenv -C builddir

Adding Python Modules

When adding new .py files:

1. Add to roster_sources in src/meson.build
2. Import in appropriate module

Schema Changes

After modifying data/cz.bugsy.roster.gschema.xml:

1. Validate: meson test -C builddir
2. Compile: glib-compile-schemas data/

Testing

Run Tests

meson test -C builddir

Manual Testing

Test both installation methods:

• Native build
• Flatpak build

Test features:

• HTTP requests (GET, POST, PUT, DELETE)
• Variables and environments
• Sensitive variables (GNOME Keyring)
• Scripts (preprocessing/postprocessing)
• Request history
• Export functionality

Debugging

Python Debugging

Use Python debugger:

import pdb; pdb.set_trace()

GTK Inspector

Enable GTK Inspector:

gsettings set org.gtk.Settings.Debug enable-inspector-keybinding true
# Then press Ctrl+Shift+D in running app

Flatpak Debugging

flatpak run --command=sh cz.bugsy.roster
# Then run python3 /app/share/roster/roster/main.py

Logs

Check logs for errors:

# Native
journalctl -f | grep roster

# Flatpak
flatpak run cz.bugsy.roster 2>&1 | tee roster.log

Code Style

• Follow PEP 8 for Python code
• Use 4 spaces for indentation
• Use type hints where practical
• Keep functions focused and well-named
• Document complex logic with comments

Next Steps

• Architecture - Technical architecture overview
• Contributing - Contribution guidelines