cruiz developer information

Architecture

The main point to understand about the application architecture is that it is split into two separate parts:

  1. The PySide6 UI (cruiz v1.3.x also had a PySide2 fallback - removed from later versions), with absolutely no Conan modules imported

  2. The workers, that can import Conan modules

The workers are functions run in separate processes to the UI. This makes use of the multiprocessing package in Python, and uses the spawn start method. This is for three reasons:

  1. spawn is the only start method supported on all platforms
  2. spawn starts a fresh Python interpreter, so since the UI has no Conan imports, this means each worker starts in a fresh environment for Conan
  3. killing processes seems to be more stable than killing threads (at least in Linux)

The ways that Conan can leak into the UI is through the multiprocessing queues, which are used for message passing between the UI and the worker processes. Data is pickled across the queues, and if the worker sends a message containing an instance of a Conan type, Conan is imported via the unpickling on the UI side when the message is received. Effort is made to detect when this occurs. An interop layer exists so that the UI can work on data that has been generated by Conan. This may require further maintenance as Conan is developed, or features of cruiz progress.

Developing in an IDE

The author has found vscode to be a useful IDE to develop and debug in, with Python, linting, rst, PySide extensions helping.

Debugging can be configured so that you can step right into the conan package to figure things out if necessary. Just add "justMyCode": false to launch.json.

More details can be found, for example, in the tutorial.

VisualStudio Code has been configured in the cruiz source workspace to format and lint code automatically.

Tox

Tox is used to run both flake8 and mypy for linting and static analysis. flake8 plugins are used to cover a number of areas.

Add the necessary tools to your Python 3 virtual environment using pip install -r requirements_dev.txt.

Running tox is as simple as

tox -e lint

Code format

cruiz uses black as a formatter.

Continuous integration

GitHub Actions are implemented for each branch. Depending on the branch, different actions are performed

Topic branches

The Python package will be built and linted.

Protected branches

As for topic branches, but additionally uploaded to Test PyPi.

Protected tags

These begin with v. As for topic branches, but additionally uploaded to PyPi.

Making a release

Releases should be planned, and semantic versioning used. Prereleases are encouraged. A Git annotated tag represents a release. Tag formats are vX.Y.Z[(a|b)N] where X is the major, Y is the minor, and Z is the patch version; a is for alpha, b is for beta, and N is incrementing non-zero integer.

Maintenance

For each new major or minor release, a branch is created called vX.Y that represents the maintenance of the family of releases vX.Y.Z. All bug fixes should be applied to the maintenance branch first, and then merged back to the default branch. Cherry-picking from the default branch to a maintenance branch should not be used.