Skip to content

Development workflow

Now that a QField plugin has been generated, let's dev it further !

Note

The following commands are to be run in the generated plugin directory, e.g. qfplugin-my-topologizer/ if the plugin name is My Topologizer (slugified to my-topologizer).

Load the plugin in QField

If you are on Linux, you may need to set the +x permission on the downloaded QField build:

chmod +x qfield-X.Y.Z-linux-x64.AppImage

Installing the QField plugin reloader in QField

  • Create a symbolic link from the generated plugin directory into the QField plugins directory:
ln -s /path/to/the/generated/directory/qfplugin-my-topologizer/my-topologizer \
    "~/Documents/QField Documents/QField/plugins"

Note

  • The QField plugins directory is located in the QField Documents directory, which is created in your home when you first run QField. If you have changed the location of this directory, please adapt the command above accordingly.
  • The symbolic link must point to the plugin directory, not the parent directory. In this example, the plugin directory is my-topologizer, which is inside the generated directory qfplugin-my-topologizer.

Test locally

Note

QGIS4 must be installed on the machine for testing! See installation instructions.

  • Install uv locally:
python3 -m pip install uv --break-system-packages
  • Create local virtualenv with system packages and sync:
uv venv --system-site-packages
uv sync
  • Add system packages to local virtual env (hacky):
SITE_PACKAGES=$(uv run python -c "import site; print(site.getsitepackages()[0])")
echo "/usr/share/qgis/python" > "$SITE_PACKAGES/qgis.pth"
  • Test that imports are fine:
uv run python -c "import qgis; print(qgis.__file__)"
uv run python -c "import PyQt6; print(PyQt6.__file__)"
uv run python -c "from PyQt6.QtCore import QT_VERSION_STR; print(QT_VERSION_STR)"
  • Clone QField locally, e.g.:
git clone --depth 1 [--branch release-4_2] https://github.com/opengisch/QField.git
  • Run tests:
uv run pytest tests -v --qgis_disable_gui

Translate the plugin

  • install the required tools:
sudo apt install -y qt6-base-dev qt6-tools-dev-tools
  • configure the translations.pro generated file with the languages you want to support, located inside the qfplugin-my-topologizer/my-topologizer/ generated plugin directory.

For instance, to support French and German, set the TRANSLATIONS variable to the following:

TRANSLATIONS += \
    main_de.ts main_fr.ts
  • generate the translations strings:
lupdate my-topologizer/translations.pro

Note

If you have both Qt5 and Qt6 tools installed, make sure you use the Qt6 ones, e.g. by using /usr/lib/qt6/bin/lupdate on Linux.

  • open the generated .ts files with Qt Linguist, using the GUI or the command line:
linguist my-topologizer/main_fr.ts
linguist my-topologizer/main_de.ts

Note

If you have both Qt5 and Qt6 tools installed, make sure you use the Qt6 ones, e.g. by using /usr/lib/qt6/bin/linguist on Linux.

  • compile the translations to .qm files:
lrelease my-topologizer/translations.pro

Or process each .ts file individually:

lrelease my-topologizer/main_fr.ts
lrelease my-topologizer/main_de.ts

Note

If you have both Qt5 and Qt6 tools installed, make sure you use the Qt6 ones, e.g. by using /usr/lib/qt6/bin/lrelease on Linux.

Bump a new release

  1. Make sure the version key is updated in the plugin's metadata.txt file.

  2. Make sure the pyproject.toml version is updated, e.g. with uv version --bump minor.

  3. Create a new tag on the main branch, e.g. git tag 0.2, then push it via git push origin 0.2.

If GitHub is the CI platform

The release CICD workflow will then automatically create the release.

If GitHub is the CI platform

It is recommended to regularly prune the tags locally with git fetch --prune --prune-tags, since PR workflows might create some temporary ones.