Skip to content

7 · Your first patch

Before you write a line: the AI acknowledgement

Upstream QGIS does not accept AI-generated contributions. Read the AI policy page in full before your first patch. The short form you are acknowledging:

  • The code, comments and commit messages I submit to QGIS are my own human work — not generated by an AI assistant.
  • The AI-assisted tooling in this repo never crosses into my QGIS commits (the environment enforces this mechanically, but the responsibility is mine).
  • I will follow the QGIS contribution process and coding standards.

Work on a branch — ideally a worktree

qgis-dev worktree add fix-vectorlayer-crash     # or <leader>pwn in Neovim
cd ../QGIS-fix-vectorlayer-crash                # already bootstrapped, warm ccache

A worktree keeps your main checkout free for the next idea; builds start warm because the ccache is shared. (A plain git switch -c fix-vectorlayer-crash in the main checkout works too.)

The patch cycle

  1. Write the fix — with a test. QGIS expects regression tests for bug fixes (tests/src/...); run yours with <leader>pT / qgis-dev test -R <name>.
  2. Document — public API changes need Doxygen (\since QGIS 3.x); the doxygen_test hook and <leader>pd will tell you what's missing. UI or behaviour changes: add [needs-docs] to the commit message.
  3. Check — <leader>pP (pre-commit over the whole branch diff) until clean.
  4. Commit — small, logical commits; imperative first line ≤ 72 chars; body explains why. The pre-commit hooks run again as a safety net.

Send it upstream

git push fork fix-vectorlayer-crash        # your fork, over ssh
gh pr create --repo qgis/QGIS --web        # describe, link the issue

In the PR description: what/why, how it was tested, screenshots for UI changes, Fixes #12345 for the issue it closes.

The moment you push, this environment's guard rails do their final job: the pre-push hook verifies no overlay file rides along, so what arrives at upstream is exactly — and only — your work.

That's the journey

From here on it's step 5–7 in a loop. Keep qgis-dev doctor green, keep the diffs boring, and enjoy the two-minute rebuilds.