Garfield Development

Design principles

The development of Garfield was guided by the principle that cash accounting must be durable and that treasurers have a fairly convenient way to collect the revenues and expenditures. Maintenance must be possible in a distributed way.

The following principles were furthermore derived from these:

  • The UI and the database are decoupled. Data manipulations are triggered by calling stored procedures in the database. Random manipulation is not possible. This means that less mistakes can happen when incoming data is properly verified. Furthermore access control is completely deferred to the database layer.
  • Modularity. A core layer provides accounting with cash boxes and user accounts. Further functionality is provided by pluggable applications. Such a plugin module commonly provides a user frontend and an admin frontend for its own data. For the accounting part a frontend widget and backend code needs to be provided, to present the resulting data of a subtotalling point.
  • A database abstraction layer that’s used to access the database in a convient way. We use SQLAlchemy and its reflection capabilities, so that the knowledge of the columns in a table is not duplicated in the code. Queries can be formulated in pure Python through the object-relational mapper, even stored procedures can be conveniently invoked without resorting to pure SQL.
  • Database migrations through SQL snippets. The approach is patch-based, not linear, which allows for truly distributed development. There is no need to agree on numbers and the application of the patches is linearized using a dependency graph.
  • Qt is used for the UI. Qt Designer is used to allow UI prototyping in a graphical editor. The UI code is split from the generic code of a module, which can then be used by scripts (e.g. the database model).
  • Client-server. We do not implement a central server, but rely on PostgreSQL to provide data storage, access control and concurrent modification through transactions.

Structure

_images/overview.png

A module usually has the following components:

  • garfield.<module>.db: Specifies the needed database patches, sets up the ORM and provides the corresponding classes. Also provides the hooks that are called when a subtotal is created.
  • garfield.<module>.qt: Provides hooks to invoke the provided GUI dialogs.
  • garfield.<module>.qt.accounting: Provides the widget that’s presented within the accounting dialog.
  • garfield.<module>.qt.<action>: The main frontend dialogs that handle the concrete user actions (e.g. item sales).
  • garfield.<module>.qt.admin: The admin frontend to modify the module-specific data.

Please note: Not all modules are already following this naming scheme.

To add a new module, you must make it known to the Garfield core. The list of modules and their hooks can be found in garfield_gui.egg-info/entry_points.txt.

Needed packages

Please note: The following might be outdated as this is documentation that’s separate from the actual code. Please refer to debian/control for most of the packages that are actually needed.

  • You need at least the following Debian packages besides Python to successfully develop Garfield:
    • pyqt4-dev-tools: Qt UI compilation
    • python-pkg-resources: entry point handling
    • python-sqlalchemy: our SQL ORM
    • python-psycopg2: PostgreSQL interface
    • python-argparse: new-style CLI argument parsing
    • python-qt4: Qt interface
    • python-dbus: DBus interprocess communication (for notifications).
    • python-dateutil: Utility functions for handling dates.
    • python-pycountry: Country codes and names.
    • python-phonenumbers: Phone number formatting (from our Debian repository).
    • qt4-designer: Qt UI designer
    • git: our Distributed Version Control System
    • texlive-latex-base: LaTex, for receipt and contract generation.
  • To build the documentation you need to install the following packages:
    • python-sphinx
    • libjs-jquery
  • For the printer module you need python-aficio2060 from our Debian repository.
  • The authentication password is usually saved in either GNOME Keyring or KWallet. If you need this functionality for development or if you’re debugging/developing it, you need these two packages:
    • python-kde4
    • python-gnomekeyring

Git access

To get Garfield’s source, this command can be run from everywhere in the world:

git clone https://opensource.fsmi.uni-karlsruhe.de/gerrit/p/garfield.git

If you’ve created an account in our Gerrit instance and want to submit patches, you will need to switch to a different repository URL (and replace USERNAME with your Gerrit username):

git remote set-url origin git+ssh://USERNAME@fsmi-dev-gerrit.fsmi.uni-karlsruhe.de/garfield.git

Commit messages should be written in English.

Coding style

The regular Python guidelines apply.

All developer visible assets like methods names, comments and developer documentation should be in English.