Packaging and Deployment

Overview

This project uses uv for dependency management and just for task automation. The packaging is handled by qgis-plugin-ci tool, which performs a git archive operation based on the CHANGELOG.md.

Prerequisites

Ensure you have the required tools installed:

  • uv: For Python dependency management

  • just: For task automation

  • Git: For version control and tagging

Development Setup

Set up the development environment using the justfile:

# Bootstrap complete development environment
just bootstrap-dev

# Or run individual steps:
just create-venv          # Create virtual environment with uv
just dev-link            # Create symbolic links for development
just trans-compile       # Compile translations

Packaging

Install Dependencies

The CI dependencies are managed through uv and defined in pyproject.toml:

# Sync CI dependencies
uv sync --group ci

Create Package

Use the justfile task to package a version:

# Package a specific version
just package 1.3.1

# The package task automatically:
# - Syncs CI dependencies
# - Copies required files (LICENSE, CHANGELOG.md, CREDITS.md)
# - Runs qgis-plugin-ci package
# - Restores development links

Manual Packaging

If you need to run qgis-plugin-ci directly:

# Package latest version from CHANGELOG.md
uv run qgis-plugin-ci package latest

# Package specific version
uv run qgis-plugin-ci package 1.3.1

Release Process

The release process is automated through GitHub Actions and follows a standard git workflow: 1 released version = 1 git tag.

Release Steps

For a tag X.y.z (must be SemVer compliant):

  1. Update CHANGELOG.md: Add the new version entry. You can write it manually or use GitHub’s auto-generated release notes:

    1. Go to project’s releases and click on Draft a new release

    2. In Choose a tag, enter the new tag

    3. Click on Generate release notes

    4. Copy/paste the generated text from ## What's changed until the line before **Full changelog**:... in the CHANGELOG.md, replacing What's changed with the tag and publication date.

  2. Update metadata.txt (optional): Change the version number in dip_strike_tools/metadata.txt. It’s recommended to use the next version number with -DEV suffix (e.g. 1.4.0-DEV when X.y.z is 1.3.0) to avoid confusion during development.

  3. Create and push the git tag:

    # Create annotated tag
git tag -a X.y.z {git commit hash} -m "Release version X.y.z"

# Push tag to main branch
git push origin X.y.z
# or push all tags at once
git push --tags

  4. Automated CI/CD: The GitHub Actions workflow will automatically:

Testing Release Process

Use the justfile to test the release process without publishing:

# Test release process locally
just release-test X.y.z

This runs the packaging steps without GitHub token and OSGEO authentication.

Troubleshooting Failed Releases

If the CI/CD pipeline fails or you need to recreate a release:

# Delete the problematic tag locally and remotely
git tag -d X.y.z
git push origin :refs/tags/X.y.z

# Fix the issue, create a new tag, and push again
git tag -a X.y.z {corrected commit hash} -m "Release version X.y.z"
git push origin X.y.z

CI/CD Pipeline

The project uses GitHub Actions for continuous integration and deployment:

  • Linter: Code quality checks with ruff

  • Tester: Run tests with pytest-qgis

  • Documentation: Build and deploy documentation

  • Package & Release: Automated packaging and publishing on tag push

Workflow Files

  • .github/workflows/linter.yml: Code linting

  • .github/workflows/tester.yml: Test execution

  • .github/workflows/documentation.yml: Documentation building

  • .github/workflows/package_and_release.yml: Release automation