devel-docs: Finish devel-docs cleanup
See: Infrastructure/gimp-web-devel#9
gitlab-mr.md was removed without replacement since the
package generation info is now on the MR template for
everyone's benefit (6245e4ee) and the test of the
text was mainly personal annotations.
This commit is contained in:
Bruno Lopes
parent
13d3643ad7
commit
f771437242
2 changed files with 44 additions and 249 deletions
|
|
@ -1,101 +1,13 @@
|
|||
---
|
||||
title: Developers documentation
|
||||
---
|
||||
# This file is read-only, please check https://developer.gimp.org
|
||||
|
||||
This manual holds information that you will find useful if you
|
||||
develop a GIMP plug-in or want to contribute to the GIMP core.
|
||||
All the developer documentation is exclusively hosted on
|
||||
[GIMP Developer website](https://developer.gimp.org/).
|
||||
|
||||
People only interested into plug-ins can probably read just the
|
||||
[Plug-in development](#plug-in-development) section. If you wish to
|
||||
contribute to all parts of GIMP, the whole documentation is of interest.
|
||||
The `devel-docs` dir only contains some branch-specific information that
|
||||
can not be hosted on the developer website, which is mainly the
|
||||
**os-support.txt** file and the **modules explanation** below.
|
||||
|
||||
[TOC]
|
||||
|
||||
## Plug-in and Filters development
|
||||
|
||||
All needed information for Plug-in and Filters development is documented on the
|
||||
[Resource Development](https://developer.gimp.org/resource/)
|
||||
section of GIMP Developer website, with exception of the following:
|
||||
|
||||
### Porting from GIMP 2 plug-ins
|
||||
|
||||
Take a look at our [porting guide](GIMP3-plug-in-porting-guide/README.md).
|
||||
|
||||
### Themes
|
||||
|
||||
GTK3 uses CSS themes. Don't be fooled though. It's not real CSS in that
|
||||
it doesn't have all the features of real web CSS, and since it's for
|
||||
desktop applications, some things are necessarily different. What it
|
||||
means is mostly that it "looks similar" enough that people used to web
|
||||
styling should not be too disorientated.
|
||||
|
||||
You can start by looking at the [official
|
||||
documentation](https://docs.gtk.org/gtk3/migrating-themes.html) for
|
||||
theme migration (from GTK+2 to 3), which gives a good overview, though
|
||||
it's far from being perfect unfortunately.
|
||||
|
||||
Another good idea would be to look at existing well maintained GTK3
|
||||
themes to get inspiration and see how things work.
|
||||
|
||||
Finally you can look at our existing themes, like the [System
|
||||
theme](https://gitlab.gnome.org/GNOME/gimp/-/blob/master/themes/System/gimp.css).
|
||||
Note though that this `System` theme is pretty bare, and that's its goal
|
||||
(try to theme as few as possible over whatever is the current real
|
||||
GTK system theme).
|
||||
|
||||
As a last trick for theme makers, we recommend to work with the
|
||||
GtkInspector tool, which allows you to test CSS rules live in the `CSS`
|
||||
tab. You can run the `GtkInspector` by going to the `File > Debug` menu
|
||||
and selecting `Start GtkInspector` menu item.
|
||||
|
||||
It also allows you to find the name of a widget to use in your CSS
|
||||
rules. To do so:
|
||||
|
||||
* Start the `GtkInspector`;
|
||||
* go on the "Objects" tab;
|
||||
* click the "target" 🞋 icon on the headerbar's top-left, then pick in
|
||||
GIMP interface the widget you are interested to style;
|
||||
* the widget name will be displayed on the top of the information area
|
||||
of the dialog.
|
||||
* Feel free to browse the various sections to see the class hierarchy,
|
||||
CSS nodes and so on.
|
||||
* The second top-left button (just next to the target icon) allows you
|
||||
to switch between the details of the selected widget and the widget
|
||||
hierarchy (container widgets containing other widgets), which is also
|
||||
very useful information.
|
||||
|
||||
Additionally you can quickly switch between the light and dark variant
|
||||
of a same theme by going to "Visual" tab and switching the "Dark
|
||||
Variant" button ON or OFF.
|
||||
|
||||
|
||||
## Core development
|
||||
|
||||
When writing code, any core developer is expected to follow:
|
||||
|
||||
- GIMP's [coding style](https://developer.gimp.org/core/coding_style/);
|
||||
- the [directory structure](#directory-structure-of-gimp-source-tree)
|
||||
|
||||
[GIMP's developer site](https://developer.gimp.org/) contain various valuable resources.
|
||||
|
||||
Finally the [debugging-tips](https://developer.gimp.org/core/debug/debugging-tips/) file contain many very
|
||||
useful tricks to help you debugging in various common cases.
|
||||
|
||||
### Newcomers
|
||||
|
||||
If this is your first time contributing to GIMP, you might be interested
|
||||
by [build instructions](https://developer.gimp.org/core/setup/).
|
||||
|
||||
You might also like to read these instructions on the process of
|
||||
[submitting patches](https://developer.gimp.org/core/submit-patch/).
|
||||
|
||||
### TODO: Core Contributors
|
||||
|
||||
As a core dev, you can trigger .appimage, .flatpak standalone packages,
|
||||
.exe Windows installer or Microsoft Store/.msixbundle to be generated
|
||||
with the MR code as explained in [gitlab-mr.md](gitlab-mr.md).
|
||||
|
||||
### Directory structure of GIMP source tree
|
||||
{height=1120px}.
|
||||
|
||||
GIMP source tree can be divided into the main application, libraries, plug-ins,
|
||||
data files and some stuff that don't fit into these categories. Here are the
|
||||
|
|
@ -103,39 +15,39 @@ top-level directories:
|
|||
|
||||
| Folder | Description |
|
||||
| --- | --- |
|
||||
| app/ | Source code of the main GIMP application |
|
||||
| app-tools/ | Source code of distributed tools |
|
||||
| build/ | Scripts for creating binary packages |
|
||||
| data/ | Data files: dynamics, gradients, palettes… |
|
||||
| desktop/ | Desktop integration files |
|
||||
| devel-docs/ | Developers documentation |
|
||||
| docs/ | Users documentation |
|
||||
| etc/ | Configuration files installed with GIMP |
|
||||
| extensions/ | Source code of extensions |
|
||||
| gimp-data/ | Raster or image data files |
|
||||
| libgimp/ | Library for plug-ins (core does not link against) |
|
||||
| libgimpbase/ | Basic functions shared by core and plug-ins |
|
||||
| libgimpcolor/ | Color-related functions shared by core and plug-ins |
|
||||
| libgimpconfig/ | Config functions shared by core and plug-ins |
|
||||
| libgimpmath/ | Mathematic operations useful for core and plug-ins |
|
||||
| app/ | Source code of the main GIMP application |
|
||||
| app-tools/ | Source code of distributed tools |
|
||||
| build/ | Scripts for creating binary packages |
|
||||
| data/ | Data files: dynamics, gradients, palettes… |
|
||||
| desktop/ | Desktop integration files |
|
||||
| devel-docs/ | Developers documentation generation files |
|
||||
| docs/ | CLI and rc files documentation (manpages) |
|
||||
| etc/ | Configuration files installed with GIMP |
|
||||
| extensions/ | Source code of extensions |
|
||||
| gimp-data/ | Raster or image data files |
|
||||
| **libgimp/** | Library for plug-ins (core does not link against) (**can have auto-generated files**) |
|
||||
| libgimpbase/ | Basic functions shared by core and plug-ins |
|
||||
| libgimpcolor/ | Color-related functions shared by core and plug-ins |
|
||||
| libgimpconfig/ | Config functions shared by core and plug-ins |
|
||||
| libgimpmath/ | Mathematic operations useful for core and plug-ins |
|
||||
| libgimpmodule/ | Abstracts dynamic loading of modules (used to implement loadable color selectors and display filters) |
|
||||
| libgimpthumb/ | Thumbnail functions shared by core and plug-ins |
|
||||
| libgimpwidgets/ | User interface elements (widgets) and utility functions shared by core and plug-ins |
|
||||
| menus/ | XML/XSL files used to generate menus |
|
||||
| modules/ | Color selectors and display filters loadable at run-time |
|
||||
| pdb/ | Scripts for PDB source code generation |
|
||||
| plug-ins/ | Source code for plug-ins distributed with GIMP |
|
||||
| po/ | Translations of strings used in the core application |
|
||||
| po-libgimp/ | Translations of strings used in libgimp |
|
||||
| po-plug-ins/ | Translations of strings used in C plug-ins |
|
||||
| po-python/ | Translations of strings used in Python plug-ins |
|
||||
| po-script-fu/ | Translations of strings used in Script-Fu scripts |
|
||||
| po-tags/ | Translations of strings used in tags |
|
||||
| po-tips/ | Translations of strings used in tips |
|
||||
| po-windows-installer/ | Translations of strings used in the Windows installer |
|
||||
| themes/ | Official themes |
|
||||
| tools/ | Source code for non-distributed GIMP-related tools |
|
||||
| .gitlab/ | Gitlab-related templates or scripts |
|
||||
| libgimpthumb/ | Thumbnail functions shared by core and plug-ins |
|
||||
| libgimpwidgets/ | User interface elements (widgets) and utility functions shared by core and plug-ins |
|
||||
| menus/ | XML/XSL files used to generate menus |
|
||||
| modules/ | Color selectors and display filters loadable at run-time |
|
||||
| pdb/ | Scripts for PDB source code generation |
|
||||
| plug-ins/ | Source code for plug-ins distributed with GIMP |
|
||||
| po/ | Translations of strings used in the core application |
|
||||
| po-libgimp/ | Translations of strings used in libgimp |
|
||||
| po-plug-ins/ | Translations of strings used in C plug-ins |
|
||||
| po-python/ | Translations of strings used in Python plug-ins |
|
||||
| po-script-fu/ | Translations of strings used in Script-Fu scripts |
|
||||
| po-tags/ | Translations of strings used in tags |
|
||||
| po-tips/ | Translations of strings used in tips |
|
||||
| po-windows-installer/ | Translations of strings used in the Windows installer |
|
||||
| themes/ | Official themes |
|
||||
| tools/ | Source code for non-distributed GIMP-related tools |
|
||||
| .gitlab/ | Gitlab-related templates or scripts |
|
||||
|
||||
The source code of the main GIMP application is found in the `app/` directory:
|
||||
|
||||
|
|
@ -153,7 +65,7 @@ The source code of the main GIMP application is found in the `app/` directory:
|
|||
| app/menus/ | Code for menus (depends: GTK) |
|
||||
| app/operations/ | Custom GEGL operations (depends: GEGL) |
|
||||
| app/paint/ | Paint core that provides different ways to paint strokes (depends: GEGL) |
|
||||
| app/pdb/ | Core side of the Procedural Database, exposes internal functionality |
|
||||
| **app/pdb/** | Core side of the Procedural Database, exposes internal functionality. (**can have auto-generated files**) |
|
||||
| app/plug-in/ | Plug-in handling in **core** |
|
||||
| app/propgui/ | Property widgets generated from config properties (depends: GTK) |
|
||||
| app/tests/ | Core unit testing framework |
|
||||
|
|
@ -163,20 +75,8 @@ The source code of the main GIMP application is found in the `app/` directory:
|
|||
| app/widgets/ | Collection of widgets used in the application GUI |
|
||||
| app/xcf/ | XCF file handling in **core** |
|
||||
|
||||
#### Auto-generated Files
|
||||
|
||||
Please notice that some files in the source are generated from other
|
||||
sources. All those files have a short notice about being generated
|
||||
somewhere at the top. Among them are the files ending in `pdb.[ch]` in
|
||||
the `libgimp/` directory and the files ending in `cmds.c` in the
|
||||
`app/pdb/` subdirectory. Those are generated from the respective `.pdb`
|
||||
files in `pdb/groups`.
|
||||
|
||||
Other files are:
|
||||
|
||||
* `AUTHORS` from `authors.xml`
|
||||
|
||||
You should also check out [gimp-module-dependencies.svg](gimp-module-dependencies.svg).
|
||||
**TODO**: this SVG file is interesting yet very outdated. It should not
|
||||
be considered as some kind dependency rule and should be updated.
|
||||
This README file is read-only.
|
||||
|
||||
Remember: all the developer documentation is exclusively hosted on
|
||||
[GIMP Developer website](https://developer.gimp.org/). Do
|
||||
not search nor add documentation files on this dir.
|
||||
|
|
|
|||
|
|
@ -1,105 +0,0 @@
|
|||
# Merge Request tricks
|
||||
|
||||
By default, a Merge Request pipeline would only build GIMP for
|
||||
Debian with merely testing purposes.
|
||||
|
||||
You might want to actually generate easy-to-install builds, in
|
||||
particular if you want it to be testable for non-developers, or
|
||||
various other reasons.
|
||||
|
||||
So, as a developer, comment: /label ~Package:`AppImage` or `Flatpak` or `Windows Installer` or `Microsoft Store`
|
||||
(this will generate the requested package for new pipelines).
|
||||
|
||||
☣️ We remind that these packages are built on-top of development code
|
||||
(i.e. work-in-progress and potentially unstable codebase likely
|
||||
containing critical bugs) with additional code which can be contributed
|
||||
by anyone (any anonymous person is allowed to propose patches as merge
|
||||
requests not only known team members).
|
||||
Therefore you should always check the merge request changes before
|
||||
running the code and never blindly trust that it is harmless. In any
|
||||
case, run these builds at your own risk. ☢️
|
||||
|
||||
## Reviewing MR branches
|
||||
|
||||
Reviewing merge requests on the Gitlab interface often leads to poor
|
||||
review, because:
|
||||
|
||||
- It doesn't show tabs, trailing whitespaces and other space issues
|
||||
which a well-configured CLI git would usually emphasize with colors.
|
||||
- The commit history is not emphasized, only the final results, but it's
|
||||
very important to check individual commits, as well as usable commit
|
||||
messages.
|
||||
- It's anyway usually much easier to review patches on your usual
|
||||
workflow environment rather than in a hard-to-use web interface.
|
||||
|
||||
There are ways to work on your local environments.
|
||||
|
||||
### Fetching MR branches automatically (read-only)
|
||||
|
||||
This first one is more of a trick, but an incredibly useful one.
|
||||
Unfortunately it is read-only, so it means you can review but not edit
|
||||
the MR yourself. Nevertheless since having to edit a MR should be the
|
||||
exception, not the rule, it's actually not too bad.
|
||||
|
||||
Edit your `.git/config` by adding a second "fetch =" rule to the
|
||||
"origin" remote. It should read:
|
||||
|
||||
```
|
||||
[remote "origin"]
|
||||
fetch = +refs/heads/*:refs/remotes/origin/*
|
||||
fetch = +refs/merge-requests/*/head:refs/remotes/origin/merge-requests/*
|
||||
url = git@ssh.gitlab.gnome.org:GNOME/gimp.git
|
||||
```
|
||||
|
||||
From now on, when you `git pull` or `git fetch` the origin remote, any
|
||||
new or updated merge request will also be fetched. \o/
|
||||
|
||||
### Pushing to a third-party MR branch
|
||||
|
||||
There are cases when you want to push to the MR branch. It should stay
|
||||
rare occasions, but it can be for instance when the contributor seems
|
||||
stuck and doesn't know how to do some things; or maybe one doesn't
|
||||
understand instructions; sometimes also some contributors disappear
|
||||
after pushing their patch and never answer to review anymore.
|
||||
|
||||
When this happen, you could merge the commit and fix it immediately
|
||||
after (but it's never good to leave the repo in a bad state, even for
|
||||
just a few minutes). You could also apply, fix and push the fixed
|
||||
commits directly, but then the MR has to be closed and it doesn't look
|
||||
like it was applied (which is not the end of the world, but it's still
|
||||
nicer to show proper status on which patches were accepted or not).
|
||||
Moreover you would not be able to pass the CI build.
|
||||
|
||||
So we will fetch the remote yet without naming the remote:
|
||||
|
||||
- Click the "Check out branch" button below the merge request
|
||||
description. Gitlab gives you instructions but we will only use the
|
||||
first step ("Fetch and check out the branch for this merge request").
|
||||
For instance if contributor `xyz` created the branch `fix-bug-123` on
|
||||
their own remote, you would run:
|
||||
|
||||
```
|
||||
git fetch "git@ssh.gitlab.gnome.org:xyz/gimp.git" 'fix-bug-123'
|
||||
git checkout -b 'xyz/fix-bug-123' FETCH_HEAD
|
||||
```
|
||||
|
||||
- Now that you are in a local branch with their code, make your fix, add
|
||||
a local commit.
|
||||
|
||||
- Finally push to the contributor's own remote with the call:
|
||||
|
||||
```
|
||||
git push git@ssh.gitlab.gnome.org:xyz/gimp.git xyz/fix-bug-123:fix-bug-123
|
||||
```
|
||||
|
||||
This assumes that the contributor checked the option "*Allow commits
|
||||
from members who can merge to the target branch.*" (which we ask
|
||||
contributors to check, and it's set by default)
|
||||
|
||||
- Now check the MR page. It will normally be updated with your new
|
||||
commit(s) and a new pipeline should be triggered.
|
||||
|
||||
- Finally if you don't need the local branch anymore, you may delete it
|
||||
locally. The nice thing is that since you didn't name the remote, it
|
||||
doesn't pollute your git output and all data will be simply disposed
|
||||
of the next time `git gc` runs (implicitly or explicitly).
|
||||
Loading…
Reference in a new issue