Development¶

Quickstart¶

Warning

This plugin is being developed on an ubuntu 24.04 machine. These instructions are not guaranteed to work on a different system. Moreover, they will very likely fail on a Windows system.

Install QGIS. Be sure to get at the minimum version 3.44;
Create a custom QGIS profile for development - This is not strictly necessary but helps with keeping your main QGIS workspace clean. Use the QGIS GUI for this (Settings -> User Profiles -> New Profile...). For the sake of these instructions, let's pretend you named your profile my-profile.
Install the pyqt5 dev tools, in order to gain access to the pyrcc5 utility:
```
sudo apt install pyqt5-dev-tools
```
Install uv;
Fork and clone this repo (assuming your github name is myself):
```
git clone https://github.com/myself/qgis-oacs-plugin.git
```
Use the provided plugin-admin CLI utility to create a virtualenv and get the QGIS Python bindings in it:
```
uv run plugin-admin --qgis-profile my-profile install-qgis-into-venv
```
Now you can work on the plugin code

Test things out locally by installing the plugin with:

uv run plugin-admin --qgis-profile my-profile install

When ready, submit a PR for your code to be reviewed and merged

plugin-admin CLI tool¶

This plugin comes with a plugin-admin CLI command which provides commands useful for development. It is used to perform all operations related to the plugin:

Install the plugin to your local QGIS user profile
Ensure your virtual env has access to the QGIS Python bindings
Build a zip of the plugin
etc.

It must be invoked like this:

# get an overview of existing commands
uv run plugin-admin --help

Installing the plugin into your local QGIS python plugins directory¶

When developing, in order to try out the plugin locally you need to call uv run plugin-admin install command. This command will copy all files into your local QGIS python plugins directory. Upon making changes to the code you will need to call this installation command again (and potentially also restart QGIS).

Tip

Perhaps a more robust set of instructions would be to: - Create a custom QGIS user profile for development (here named oacs-dev) - Create a sample QGIS project to aid in development (here named oacs-plugin-sample-project.qgz) execute the following:

uv run plugin-admin --qgis-profile oacs-dev install \
    && qgis \
        --profiles-path ${HOME}/.local/share/QGIS/QGIS3 \
        --profile oacs-dev \
        --project oacs-plugin-sample-project.qgz

Improving the development cycle with the plugin reloader plugin¶

The plugin reloader plugin is very handy for development, as it allows speeding up the cycle of:

Work on the plugin code
Re-install it locally
Close QGIS
Open QGIS again

With the plugin reloader you can both:

Reload the plugin in QGIS without having to restart the whole application. Just select it as the reloader target;
Run some external command(s) just before the plugin is reloaded. This allows us to call plugin-admin to re-install the plugin without leaving the QGIS window. For example:
```
cd ~/dev/qgis-oacs-plugin
uv run plugin-admin --qgis-profile my-profile install
```

Releasing new versions¶

This plugin uses an automated release process that is based upon github actions. New versions shall be released under the semantic versioning contract.

In order to have a new version of the plugin released:

Be sure to have updated the CHANGELOG.md
Be sure to have updated the version on the pyproject.toml file AND to have synced the uv lockfile after having made this change
Create a new git annotated tag and push it to the repository. The tag name must follow the v{major}.{minor}.{patch} convention, for example:
```
git tag -a -m 'version 0.3.2' v0.3.2
git push origin v0.3.2
```
Github actions will take it from there. The new release shall appear in the custom QGIS plugin repo shortly
Do a post-release commit setting the version back to dev