Submit your first patch

Table of Contents

The GIMP project uses Gitlab’s issue tracker to coordinate bug reports and contributed fixes. Gitlab is also used for enhancement requests and the preferred way to submit patches for GIMP is to make a merge request .

On www.gimp.org you can find a document describing how to report GIMP Bugs . If this is what you were interested in, stop there. The below instructions will go further and explain you what to do to contribute your own code changes.

The instructions in this page also apply for GEGL, babl and other repositories hosted by the GIMP project .

Set up your developer environment

The first step is to get the latest source code and build GIMP. For this, you will be interested by the Setting up your developer environment section.

GIMP relies on various technologies, and if our tutorials are not enough, you should try to document yourself on the proper upstream documentation. Such technologies include:

git
meson (master branch only)
Standard autotools procedure (gimp-2-10 branch only)

Finding what to fix or implement

This may seem obvious but is apparently a big problem for many first-time contributors: what to work on?

The most common advice is: if you use GIMP, did you never encounter a bug or annoyance you wanted to see fixed? This is most often the best tip, because then you have personal reasons to see your contribution through and feel extra rewarded at the end (and each time you use GIMP and the feature you fixed!). Most of us started this way, often with very simple patches on some little issue we had.

Of course, a second good tip is to not necessarily see too big for your first patch, or at least to contribute according to your experience. A total beginner in development trying to implement a very important core feature might just exhaust oneself.

If you have absolutely no such problem of your own, below is a list of links to get you started:

Checkout the source

To checkout the source of GIMP open the command line and type

git clone https://gitlab.gnome.org/GNOME/gimp

Note: of course, replace the GIT URL and branch names if you want to contribute to another GIMP-hosted project , such as GEGL or babl. From now on, it will be assumed you understood you have to tweak these instructions depending on the actual target project. This is the last time we repeat ourselves about this.

Depending on whether you want to contribute for the stable version only or the development version, you will have to checkout a specific branch. GIMP branch naming scheme is that our stable branch is in the form gimp-<major>-<minor>. Development version is in the historically named master branch.

So say you want to fix a bug which happens only in the GIMP 2.10 stable branch, then checkout the branch this way:

git checkout gimp-2-10

On the other hand, to work on the main development branch:

git checkout master

For simplicity sake, in the remnant of this tutorial, we will use the environment variable $BASE_BRANCH to mean either origin/gimp-2-10 or origin/master depending on the branch you chose here. Each time you see this variable, remember it means you need to use your own chosen base branch.

🔊 For new features or bugs which affect all branches, we request that you first contribute them on the master branch. Once it is reviewed and merged, you are more than welcome to backport the fix or the feature to the gimp-2-10 branch. The reason is pretty simple: if you fix or improve something in a stable version, then disappear, it creates a regression bug on the development version (an issue which used to be fixed and not anymore). And that makes more work for maintainers. So always work on master first for anything touching both codebases.

Finally don’t forget you should always work on latest code in your branch, hence pull:

git pull origin

Modifying the source

It’s time to write code. By the way, do not forget to read our Coding Style document before writing any code. Having to spend a lot of time on style in the review can feel a waste of time for both you and the reviewer. Ideally you read and follow our guidelines from the start.

We advise to create a local branch for your modifications, as it will make it easier for you to track your work and won’t pollute your main branch (which will be annoying in particular when you want to work on several topics at once).

So first choose a branch name. It can be anything, but a naming scheme we like in GIMP is naming it like wip/<your-username>/<meaningful-name>. E.g. imagine you work on fixing a segfault when doing abc, then I (Jehan) could name my branch wip/Jehan/fixing-abc-segfault.

And finally I would create the branch, based on the $BASE_BRANCH codebase (remember: replace $BASE_BRANCH with origin/master or origin/gimp-2-10 if you work for GIMP 2.10 only, as explained previously ):

git checkout -b wip/Jehan/fixing-abc-segfault $BASE_BRANCH

This branch will now contain your source. Do changes while on this branch, commit often (this will NOT affect other people’s repository).

ℹ️ At any time, if you forget what is the name of your branch, type git branch to see which branch you are working on).

To see the status of your branch (which files were changed/added/removed) run:

git status

In order to have a graphical user interface to browse the current state of the branch, and to see the exact changes you made to specific files, you can use graphical git frontends, such as gitk.

In order to commit your changes (i.e. save the current state of the source) do:

git commit -a -m "Message"

(replace “Message” with your own message, describing the current commit)

Note that if you have a long commit message (longer than 80 characters), then you should brake it into a summary line (of up to 80 characters) and description lines (directly after the summary) which describe the commit with more details (again, each of the lines should not be more than 80 characters long).

Finalizing your changes

When finished (and committed code one final time), since some time may have passed and you must always submit patches based on the newest code, run:

git rebase $BASE_BRANCH

Fix any merge errors and test your code again (after finishing this, execute git rebase $BASE_BRANCH again if it took you long to fix the merge errors).

Contributing upstream

Using Gitlab merge request workflow

Nowadays most people just create merge requests. The process is as follow:

Go on our main repository page: https://gitlab.gnome.org/GNOME/gimp
If you are not logged-in, click the “Sign in / Register” button on the top-right. Create an account if necessary. You may either create an account from scratch with a login and password, or sign in with an existing account from another supported platform (Gitlab.com, OpenID, Github and Google accounts at time of writing).
Once logged, you will see a new “Fork” button (still top-right, but below the “Sign in / Register” button, right next to the “Star” one) with a number next to it. Click this button, then follow the instructions.
Once your fork is created, click the blue “Clone” button to choose one of the clone URLs (SSH or HTTPS). Copy the chosen URL. Let’s say the copied URL is now $MY_GIMP_CLONE.
Add a remote in your git repository with the following command:
```
git remote add mine $MY_GIMP_CLONE
```
Note that mine is just a random name you set for this remote. This is a naming scheme I personally use to differenciate with the origin remote, which is the name I usually keep for the upstream repository.

Now you are free to name it however you want. Some people even do the opposite as they fork first, then clone their own repository (which is called origin by default) and name the upstream repository something else (e.g. upstream). It’s all up to your workflow choices.
Now push your branch to your repository this way:
```
git push -u mine wip/Jehan/fixing-abc-segfault
```
Note: remember that wip/Jehan/fixing-abc-segfault is how we named our hypothetical branch. Yours would be called something else.
Once you did all this, go again to GIMP repository web page . Chances are that you will see a green banner at the top saying something like this:
```
 ✅ You pushed to wip/Jehan/fixing-abc-segfault at Jehan / gimp 10 minutes ago
```
Click the “Create merge request” button in the banner.

If you don’t see this green banner (possibly too much time has passed since you pushed), just go to the merge requests page, click “New merge request”, select the source repository (yours) and branch (wip/Jehan/fixing-abc-segfault), as well as the target repository (GNOME/gimp) and branch (whatever was $BASE_BRANCH), then click “Compare branches and continue”.
Fill the various fields appropriately:
- Proper title and description explaining well what your patch is supposed to fix and why.
- Mention a bug report number if it exists.
- Are there any known problems with the patch? It’s alright to send not totally complete patch, for instance if you want to advertize you are working on a bug (avoiding work duplication by other developers), or you feel blocked and need some advices and opinions on your current work-in-progress. When this is the case, explain this clearly in the description and mark the merge request as “Draft” by clicking the “Start the title with Draft:” link just below the “Title” field.
Click “Create merge request”.
Done! You made your first contribution, congratulation!

Upload a patch in a bug report

As an alternative method, we still accept simple patch files, as was done since the dawn of times (or nearly! 🤭).

The command to create a patch in git is extra easy:

git format-patch $BASE_BRANCH

This will give you patch files in the form of git commits with names like 0001-plug-ins-Use-string-literal-as-format-in-metadata-p.patch.

For each one of your commits which is not in $BASE_BRANCH, a patch file will be created in the directory (the patch files will be numbered by the order of the commits). If you want to avoid polluting your current working directory with many patch files, you can use the -o <output-folder> option (replacing <output-folder> with the folder where you want the patch files to be created of course).

Alternatively if your fix is made in several commits, you may prefer to have a single file. It is possible by redirecting the output to stdout then to a file with this command:

git format-patch --stdout $BASE_BRANCH > fixing-abc-segfault.patch

Now, all you have to do is to upload the patch file(s) to the bug report discussing the bug you were fixing or feature you were implementing.

Some general advices on git usage

Have proper authorship set up in git.
Create relevant commit messages.
We are not against multi-commit merge requests/patches. Quite the opposite even! If your code is long and complex, we prefer well compartimented and organized work.

You could have for instance a commit adding a new function in libgimp and another commit using this new API in plug-ins. Or you could some core concept introduced in app/core, without any GUI, in a first commit; then create some new fancy widget manipulating this new concept in app/widgets/, implemented in its own commit; and finally actually use the new widget from app/dialogs/ in a further commit. And so on.

You should avoid just updating your merge request with micro fix commits. I.e. when we review your code and tell you to fix coding style, don’t add a commit “Fix coding style”. Or a commit “Fix a typo”. Even actual bugs, if we see a bug in a commit, just fix the bug within the commit, not separately, so that when we actually merge it, every individual commit is bugless (hopefully!). Therefore you are expected to amend your existing commits with either git commit --amend (if you just fix your last commit) or git rebase --interactive (when you need to rebase one or more older commits). We want to merge only clean commits if possible.

Now we understand that this is harder, and it can show more challenging to total beginners as it can feel advanced git usage (especially the interactive rebase). This is when we will squash your commits, so don’t worry too much.

On the other hand, if you are an experienced developer and rebasing your branch doesn’t scare you, just feel free to reorganize your commits into nice logical commit units. This is exactly what we like, and don’t mind at all merging a 10-commit merge request if they are all perfectly logical units which a future developer can look at and find useful information for debugging or understanding the original idea of a change.