Skip to content

Latest commit

 

History

History
176 lines (133 loc) · 8.84 KB

development.md

File metadata and controls

176 lines (133 loc) · 8.84 KB
Raw

Plugin development

Setup

Instructions are aimed at developers using MacOS, but similar steps should work on different platforms as well.

Instructions were confirmed to be working well with a combination of: Python 3.9.5, QGIS 3.30+, and PyQT 5.

  1. Install QGIS app from https://qgis.org/en/site/forusers/download.html
  2. We rely on qgis_plugin_tools, so when cloning the repo, make sure to clone it recursively, with submodules:
git clone --recurse-submodules https://github.com/UnfoldedInc/qgis-plugin.git
  1. Set up tools:
python3 --version # make sure that you're using Python 3.9.5
pip3 install --upgrade pip # upgrade pip to latest
pip3 install --upgrade setuptools # upgrade setuptools to latest
  1. Install Qt and PyQT:
brew install qt@5 # our plugin relies on v5, so we make sure it's that version
export PATH="/opt/homebrew/opt/qt5/bin:$PATH" # makes sure that qmake is in your PATH
pip3 install pyqt5-sip
pip3 install pyqt5 --config-settings --confirm-license= --verbose # in some cases, the install script gets stuck on license step and this way we just automatically confirm it
  1. Install dependencies:
cd qgis-plugin
pip install -r requirements.txt

export PYTHONPATH=/Applications/Qgis.app/Contents/Resources/python # this makes sure that the version of python with bundled `qgis` module can be found
  1. The build script:

If you're on Mac, you want to comment out the lines #70 and #71 in qgis-plugin/Unfolded/qgis_plugin_tools/infrastructure/plugin_maker.py. This is because Apple returns "darwin" as a OS identifier, so this OS check mistakenly thinks it's a Windows machine, and instead, we just let it fall through to the actual case for Mac.

Now you can run the build script and deploy it to the QGIS' plugins folder:

cd qgis-plugin/Unfolded
python3 build.py deploy

This should be the end of your setup and if you manage to run build.py script without any errors, that's a confirmation that everything is set up correctly.

Development workflow

  • make changes to the plugin inside /Unfolded folder
  • run python3 build.py deploy, this packages the plugin and copies it to the QGIS' plugins folder (usually /Users/<username>/Library/Application Support/QGIS/QGIS3/profiles/default/python/plugins; or see plugin's dir location)
    • this does not publish the plugin to the official plugin registry, just installs it locally! (for releasing it to the remote registry, see Creating a release section)
    • additionally, you can set up a filesystem watcher to monitor entire folder and automatically execute the deploy command so you don't have to do it manually every time
  • to use the freshly "deployed" plugin inside QGIS you can, either:
    • restart QGIS app, and it will reload all plugins; or
    • go to "Installed Plugins" and deselect and then again select your plugin in the list, effectively reloading it; or
    • use plugin-reloader plugin (← this has the best DX and is recommended)

For debugging, use:

  • dev log (via View → Panels → Log Messages)
    • this gives you multiple output windows for all the different plugins and internal QGIS python interpreter, and is basically the main debugging tool you'll be using
  • REPL Python console (via Plugins → Python Console)
    • qgis module is available to all the plugins, and is automatically bound to them when executing plugins and is not available as a general dependency that you can freely import and use in normal Python scripts, so this is the only way you have access to it in any Python environment other than within QGIS plugin runtime
  • it's recommended to set up some typechecker and Python language server in your IDE to get a good DX and minimize the risk of errors
    • for VS Code:
      • mypy typechecker
      • pylance language server
      • Qt for Python for PyQt5 support
      • also consider adding this config line to your .vscode/settings.json (this makes sure it can find qgis module as well): 
        {
  "python.analysis.extraPaths": ["./kepler", "./keplergl", "./Unfolded", "/Applications/Qgis.app/Contents/Resources/python", "/Applications/Qgis.app/Contents/Resources", "${userHome}/.pyenv/versions/3.9.5/lib/python3.9/site-packages", "${userHome}/.pyenv/shims/pytest"]
}

Another useful thing is to have both versions of the plugin installed - the current, officially available version and your development version:

  • install the regular version from the registry
  • before running python3 build.py deploy script, update name in metadata.txt to something like name=Unfolded-dev
  • now when you run the script, a new plugin with Unfolded-dev name will appear along side the regular one in the QGIS plugins directory and plugins listing
  • ❗️ don't commit these changes to metadata.txt when doing a release (unless that's your actual intention ofc; this is just for development), just keep them in git's unstaged changes e.g.
  • you can also update icon and naming in other places to help differentiate it
image
example: both versions of the plugin active (official and dev), with different art

Adding or editing source files

If you create or edit source files make sure that:

  • they contain relative imports 
    from ..utils.exceptions import TestException # Good

from Unfolded.utils.exceptions import TestException # Bad
  • they will be found by build.py script (py_files and ui_files values)
  • you consider adding test files for the new functionality

QGIS documentation and help

Testing

Install Docker, docker-compose and python packages listed in requirements.txt to run tests with:

python build.py test

Translating

Translating with transifex

Fill in transifex_coordinator (Transifex username) and transifex_organization in .qgis-plugin-ci to use Transifex translation.

Pushing / creating new translations
  • First install Transifex CLI and qgis-plugin-ci
  • Make sure command pylupdate5 works. Otherwise install it with pip install pyqt5
  • Run qgis-plugin-ci push-translation <your-transifex-token>
  • Go to your Transifex site, add some languages and start translating
  • Copy push_translations.yml file to workflows folder to enable automatic pushing after commits to master
  • Add this badge to the README
Pulling

There is no need to pull if you configure --transifex-token into your release workflow (remember to use Github Secrets). Remember to uncomment the lrelease section as well. You can however pull manually to test the process.

  • Run qgis-plugin-ci pull-translation --compile <your-transifex-token>

Translating with QT Linguistic (if Transifex not available)

The translation files are in i18n folder. Translatable content in python files is code such as tr(u"Hello World").

To update language .ts files to contain newest lines to translate, run

python build.py transup

You can then open the .ts files you wish to translate with Qt Linguist and make the changes.

Compile the translations to .qm files with:

python build.py transcompile

Creating a release

Follow these steps to create a release

  • Add changelog information to CHANGELOG.md using this format
  • Update PLUGIN_VERSION variable in sentry.py
  • Make a new commit. (git add -A && git commit -m "Release v0.1.0")
  • Create new tag for it (git tag -a v0.1.0 -m "Version v0.1.0")
  • Push tag to Github using git push --follow-tags
  • Create Github release
  • qgis-plugin-ci adds release zip automatically as an asset