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:
Begin by cloning the QuickTile repository. either directly or from a fork you’ve made on GitHub:
git clone email@example.com:ssokolow/quicktile.git
Install the runtime dependencies.
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:
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)
ImageMagick (to combine the frames of the animation into an animated GIF)
Gifsicle (to optimize the animation)
Rely on the
./quicktile.shoption for running QuickTile without installing it as described in C. Run QuickTile without installing it.
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.
QuickTile’s documentation contains extensive TODO notes which are omitted from release versions.
To enable inclusion of these development notes…
todo_include_todos = Truein
(cd docs; make html).
Your developer documentation should now exist in
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.
If Sphinx fails to notice that part of the documentation should be
rebuilt, a rebuild can be forced either by deleting the
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:
egrep 'XXX|TODO|FIXME' -nR *.py quicktile functional_harness
PyLint should also report these.
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.
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 beyond those needed to ensure that the Travis-CI badge in the sidebar is current as of the page load.
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.
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.__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.keybindermodule 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.utilmodules, 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.
quicktile.commandsmodule 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.
quicktile.versionmodule exists only to allow
setup.pyand the rest of QuickTile to share a single definition of the version number without
setup.pyhaving to import actual QuickTile code.
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.
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
# type: ignoremust be approved on a case-by-case basis.
All Flake8 and PyLint complaints must either be resolved or whitelisted. New
pylint: disable=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
quicktilepackage 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.utilmodule 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 recommended way to submit them is via pull request, as this will automatically submit them to the various continuous testing services that run on the QuickTile repository, as well as making it as simple as possible for me to examine and accept them.
QuickTile’s current minimum compatibility target is Kubuntu Linux 16.04 LTS.
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.
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.  
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 Extensions section in the resulting dialog, and verifying that no extensions other than VNC are present.from the VirtualBox menu bar, selecting the
For best results, configure your virtual desktop with the following characteristics:
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.)
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.
To run a complete set of everything that can be completed quickly, please use the following command from the root of the project:
It will perform the majority of the tests which will be run by Travis-CI when you open a pull request, while still completing in under 5 seconds with a hot cache on an old 2-core Althon with no SSD.
The following will be run:
MyPy to check for violations of the type annotations.
Flake8 for basic static analysis and code style checking
doctest to check for broken code examples in the API documentation
make coverageto check documentation coverage (currently of questionable reliability)
While the dependency on system packages such as PyGObject limits its utility,
you may also use tox to test that QuickTile’s
setup.py packaging process
works properly. (However, bear in mind that you will need to edit
if your system Python is not version 3.5 as found on Kubuntu Linux 16.04 LTS.)
Bear in mind that, while not yet incorporated into convenient scripts, the following tests will also be run by the ALE analysis plugin for my text editor when I examine your contribution:
Bandit (You can run this as
bandit quicktileafter installation.)
PyLint (Assuming you have your system configured to complain about deprecation warnings as I do, I suggest running PyLint as
pylint3 --rcfile=pylintrc quicktile 2>/dev/null)
While it currently relies on an ugly hack which hard-codes Openbox and Zenity as dependencies, and does not yet assert that windows wind up in the expected states, you may also find the beginnings of a functional test suite useful as a way to exercise the code and check for uncaught exceptions:
Bear in mind that, even once it is more mature, it will remain excluded
run_tests.sh because it takes too long to be part of a
comfortable edit-test cycle.
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.