Developer’s Guide

Setting up a Development Environment

It should be possible to develop QuickTile on any POSIX-compatible platform with X11-based graphics. However, Linux is the only officially supported option.

To ensure your changes get accepted as quickly as possible, please bear in mind the testing requirements.

On the operating system you intend to use for development:

1. Begin by cloning the QuickTile repository. either directly or from a fork you’ve made on GitHub:

   git clone git@github.com:ssokolow/quicktile.git
   

2. Install the runtime dependencies.

3. Install Xvfb, Openbox, and Zenity (eg. sudo apt install xvfb openbox zenity) for the functional tests.

3. Either use the following command to install QuickTile’s additional development-time dependencies, or manually install the dependencies listed therein:

   pip3 install -r dev_requirements.txt
   

   These dependencies fall into one of two categories:

   • Source code verification (Ruff for static analysis and code style, MyPy for checking type hints, PyTest for test discovery, and Coverage.py for determining test coverage)

   • Documentation generation (Sphinx, sphinx-autodoc-typehints, and sphinxcontrib-autoprogram)

4. If you intend to modify the illustrations or demonstratory animation, you will also require the following to regenerate the built files:

   • A POSIX-compatible environment (For tools such as find)

   • GNU Make (to run the Makefiles used to automate the process)

   • Inkscape (to render the SVG sources to PNG)

   • OptiPNG and AdvanceCOMP (to optimize the illustrations)

   • ImageMagick (to combine the frames of the animation into an animated GIF)

   • Gifsicle (to optimize the animation)

5. Rely on the ./quicktile.sh option for running QuickTile without installing it as described in Setting Up Global Hotkeys.

   This combination of full access to Git functionality and the ability to run the changed code without needing to install first provides for the simplest development environment, and makes it easy to remove the development version and revert to the release versions once you are finished.

Building Development Documentation

QuickTile’s documentation contains extensive TODO notes which are omitted from release versions.

To enable inclusion of these development notes…

1. Uncomment todo_include_todos = True in docs/conf.py

2. Run (cd docs; make html).

3. Your developer documentation should now exist in docs/_build/html/.

The resulting API documentation will include in-line TODO annotations, as well as a complete listing at the bottom of the doc:apidocs/index page.

Note

If Sphinx fails to notice that part of the documentation should be rebuilt, a rebuild can be forced either by deleting the _build/html directory or by running (cd docs; make html SPHINXOPTS=-E) instead.

There also exist TODO comments in the source code (usually ones that shouldn’t be seen as drawing attention away from the ones in the Sphinx docs) which can be searched for by running the following command in the project root:

grep -E 'XXX|TODO|FIXME' -nR *.py quicktile tests

Regenerating Documentation Graphics

To regenerate the illustrations, run the following command:

(cd docs/diagrams; make) && (cd docs; make html)

To regenerate the animation, run the following command:

(cd docs/animation; make) && (cd docs; make html)

You only need to do this if you’ve modified the original SVG files.

Documentation Privacy Policy

Out of respect for user privacy and to make offline use of this documentation as robust as possible, this website/manual makes no external HTTP requests.

To mitigate the risk of such requests slipping in through non-obvious means, such as use of the Sphinx :math: role pulling in a CDN-hosted copy of MathJax, a Content Security Policy meta-tag has been added to the header of the site template.

It is preferred that you check your browser’s developer console for reports of requests blocked by the CSP rules on the relevant pages before submitting changes to the manual or docstrings.

High-Level QuickTile Architecture

Quicktile is fundamentally built around a somewhat HTTP-like request-response model. The user requests an action, QuickTile performs that action, and then it goes back to waiting for another event.

Any state which needs to persist between these event handlers should be stored as X11 window properties using the quicktile.wm.WindowManager.set_property() and quicktile.wm.WindowManager.get_property() methods.

Quirks of the Codebase’s Structure

• The quicktile.__main__ module is currently responsible for parsing configuration files and command-line arguments, migrating old configuration versions, initializing other components, and stitching them together. It is slated to be broken up into smaller, more task-specific modules.

• At the moment, due to an incomplete refactoring during the GTK+ 3 port, the quicktile.keybinder module is still structured as if optional, though it is now required for its role in managing the Xlib connection.

  Due to oddities in how the X11 protocol behaves when interacting with short-lived connections, you are likely to get strange and confusing bugs if the keybinder is not allowed to properly carry out its responsibility for integrating X11 into the QuickTile event loop.

  (Indeed, the bugs that still need to be rooted out of the QuickTile event loop stem from my not having properly rooted out bugs relating to X11 and short-lived applications.)

• At present, window management is split between the quicktile.wm and quicktile.util modules, with the former being concerned with communication with the outside world and the latter having temporarily become a grab-bag of everything that is so self-contained as to be easy to unit test.

• The quicktile.commands module also needs to be refactored as it currently contains the framework for registering and executing tiling commands and the shared setup code for them (lumped into a single class) as well as all of the commands themselves.

Good Development Practice

Before making changes you intend to have merged back into QuickTile’s master branch, please open a feature request on the issue tracker to propose them. This will allow me to bring up any non-obvious design concerns which might complicate, delay, or preclude my accepting your changes.

Note

Please bear in mind that QuickTile is still catching up after a decade of spotty maintenance and it may take time for your changes to get proper attention.

When working on QuickTile, please keep the following code-quality goals in mind as, if you do not, then merging your changes may have to wait until I can revise them:

• All function arguments should bear complete type annotations which pass MyPy’s scrutiny and use of typing.Any or # type: ignore must be approved on a case-by-case basis.

• All Ruff complaints must either be resolved or whitelisted. New whitelisting annotations must include comments justifying their presence, except in self-evident cases such as URLs in docstrings which exceed the line-length limit.

• All code within the quicktile package must have complete API documentation that renders through Sphinx to a standard consistent with existing documentation.

• doctests count as implicit API requirements and changes to them should not be made frivolously.

• The percentage of unit test coverage in the quicktile.util module should not decrease. (Enforcing this standard outside of that module will not be feasible until further refactoring and test harness work is completed.)

Once your changes are ready, the standard way to submit them is via pull request against the master branch, as this will automatically trigger a test run, as well as making it as simple as possible for me to examine and accept them.

Testing Your Changes

Testing Environment Concerns

As of this writing, QuickTile’s current minimum compatibility target is Kubuntu Linux 24.04 LTS. This may be broadened as the testing infrastructure is modernized.

If this is not what you are running, I suggest using VirtualBox for compatibility testing, as it is easy to set up and has support for virtual machines with multiple monitors.

Warning

When installing VirtualBox, be sure to not install the Oracle VM VirtualBox Extension Pack, as it phones home and Oracle has been making large licensing demands of people who they believe to be using it commercially. [1] [2]

Those using only VirtualBox packages provided by their Linux distribution’s official package repositories should have no need to worry, but its absence can be confirmed by choosing File ‣ Preferences… from the VirtualBox menu bar, selecting the Extensions section in the resulting dialog, and verifying that no extensions other than VNC are present.

Should this prove too concerning, KVM-based solutions such as virt-manager or GNOME Boxes should also serve equally well though I can give no advice on setting them up for multi-monitor support.

For best results, configure your virtual desktop with the following characteristics:

1. Differently-sized monitors (Certain bugs in moving windows from monitor to monitor can only be triggered if one monitor is larger or smaller than another.)

2. Panels (taskbars and the like) on an edge where the monitors are adjacent but do not line up.

   Suppose you have a 1280x1024 monitor and a 1920x1080 monitor, and the tops are aligned. Place panels on the bottom, so that the reservation for the shorter monitor will also have to cover the dead space below it and has the best chance of triggering any dead-space-related bugs in the code for calculating usable regions.

Automated Testing

To run a complete set of all tests, please use the following command from the root of the project:

./run_tests.sh

The following will be run:

• MyPy to check for violations of the type annotations.

• Ruff for basic static analysis and code style checking

• PyTest and doctest to run the unit tests (currently of limited scope)

• doctest to check for broken code examples in the API documentation

• Sphinx’s make coverage to check documentation coverage (currently of questionable reliability)

In lieu of a proper functional test suite, please manually execute all tiling commands which rely on code you’ve touched and watch for misbehaviour.

Adding Yourself to the AUTHORS List

When making a contribution, please also add yourself to the Authors section and regenerate the AUTHORS file in the root of the project.

This can be done as follows:

1. Edit docs/authors/index.rst

2. Regenerate the HTML version of the documentation and verify that it looks right. (Run make html from inside the docs folder.)

3. Run ./docs/update_authors.sh to regenerate AUTHORS

4. Verify that AUTHORS looks right.

5. Commit your changes.

Additions to the “The Program” section should be phrased so that reading the definition list title and body together form a sentence in the simple past tense. However, the body portion should still be capitalized as if it is a complete sentence.

Please combine related changes into a single high-level description of the user-visible changes. This rule may be relaxed when it would unfairly downplay the amount of work involved.

Please try to make proper use of Sphinx markup to indicate things such as command and function names. Constructs such as :py:mod:`round` may be used to reference identifiers within dependencies but be aware that, because generation of AUTHORS considers the document in isolation, markup which attempts to generate cross-references to the rest of the manual will trigger warnings when update_authors.sh is run and may not be be used.

A Good Example:

Yuting/Tim Xiao
    Made the wndow-tiling heuristics more robust.

A Bad Example:

Yuting/Tim Xiao

    * Increase closest-dimension matching fuzziness to 100px.
    * Update min-distance calculation in cycleDimensions to use
      lengths instead of area.
    * Always use the first given configuration for untiled windows.