dnrops
/
gimp
mirror of https://github.com/GNOME/gimp.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

devel-docs: update the developer documentation further. 

Add some more text and links to existing documents.

I also remove 3 files which are now either outdated or whose contents is
also written (with more or less similar text) in other more up-to-date
files.
This commit is contained in:
Jehan 2022-01-23 01:00:56 +01:00
parent 67a1d9f4d0
commit 4065c33bf0
4 changed files with 173 additions and 92 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

61
devel-docs/README
View File

@ -1,61 +0,0 @@
Developers documentation
------------------------
This directory holds information that you will find useful if you
develop a GIMP plug-in or want to work on the GIMP core.
See https://wiki.gimp.org/index.php/Main_Page for more information.
app - setup for documentation of the GIMP core;
not built by default since it is huge and
only relevant for core developers
libgimp
libgimpbase
libgimpcolor
libgimpconfig
libgimpmath
libgimpmodule
libgimpthumb
libgimpwidgets - complete libgimp documentation generated from
the source; see README.gtkdoc
tools - the source code for tools used to generate
documentation
gitlab-milestones.txt - describes how the GIMP project uses
milestones in the GNOME gitlab issue tracker
commit-rules.txt - describes rules and things to think
about when creating GIMP commits
contexts.txt - describes how GimpContexts are used in GIMP
debug-plug-ins.txt - how to debug GIMP plug-ins
exif-handling.txt - how GIMP should handle EXIF data
includes.txt - the policy for inclusion of header files
parasites.txt - descriptions of known parasites
release-howto.txt - a check-list for doing a GIMP release
submitting-patches.txt - how to submit a patch for GIMP
tagging.txt - how resource tagging in Gimp works
ui-framework.txt - describes how the GIMP UI framework functions and
how it is implemented
undo.txt - description of the undo system
structure.xml - a DocBook article that gives an overview on
the directory structure of the GIMP source tree,
also check out gimp-module-dependencies.svg
gbr.txt - description of the GBR format used to store
pixmap brushes
ggr.txt - description of the GGR format used to store
GIMP gradients
gih.txt - description of the GIH format used to store a
series of pixmap brushes
gpb.txt - OBSOLETE: description of the GPB format for
pixmap brushes
pat.txt - description of the PAT format for patterns
vbr.txt - description of VBR format used for
"generated" brushes
xcf.txt - description of Gimp's XCF format

174
devel-docs/README.md
View File

@ -118,6 +118,13 @@ TODO: at least in C and in one of the officially supported binding
### Porting from GIMP 2 plug-ins
### Debugging
GIMP provides an infrastructure to help debugging plug-ins.
You are invited to read the [dedicated
documentation](debug-plug-ins.txt).
## Script-fu development
`Script-fu` is its own thing as it is a way to run Scheme script with
@ -133,12 +140,92 @@ Scheme mini-interpreter and therefore `Script-fu` scripts do not use
## GEGL operation development
## Custom data
This section list all types of data usable to enhance GIMP
functionalities. If you are interested to contribute default data to
GIMP, be aware that we are looking for a very good base set, not an
unfinite number of data for all possible usage (even the less common
ones).
Furthermore we only accept data on Libre licenses:
* [Free Art License](https://artlibre.org/licence/lal/en/)
* [CC0](https://creativecommons.org/publicdomain/zero/1.0/)
* [CC BY](https://creativecommons.org/licenses/by/4.0/)
* [CC BY-SA](https://creativecommons.org/licenses/by-sa/4.0/)
Of course you are free to share data usable by GIMP on any license you
want on your own. Providing them as third-party GIMP
[extensions](#gimp-extensions-gex) is probably the best idea.
### Brushes
GIMP currently supports the following brush formats:
* GIMP Brush (GBR): format to store pixmap brushes
* GIMP Brush Pipe (GIH): format to store a series of pixmap brushes
* GIMP Generated Brush (VBR): format of "generated" brushes
* GIMP Brush Pixmap (GPB): *OBSOLETE* format to store pixel brushes
* MyPaint brushes v1 (MYB)
* Photoshop ABR Brush
* Paint Shop Pro JBR Brush
We do fully support the GIMP formats obviously, as well as MyPaint
brushes, since we use the official `libmypaint` library. We are not sure
how well we support other third-party formats, especially if they had
recent versions.
If you are interested in brushes from a developer perspective, you are
welcome to read specifications of GIMP formats:
[GBR](specifications/gbr.txt), [GIH](specifications/gih.txt),
[VBR](specifications/vbr.txt) or the obsolete [GPB](specifications/gpb.txt).
If you want to contribute brushes to the official GIMP, be aware we
would only accept brushes in non-obsolete GIMP formats. All these
formats can be generated by GIMP itself from images.
If you want to contribute MyPaint brushes, we recommend to propose them
to the [MyPaint-brushes](https://github.com/mypaint/mypaint-brushes/)
data project, which is also used by GIMP for its default MyPaint brush
set.
Otherwise, you are welcome to provide brush set in any format as
third-party [extensions](#gimp-extensions-gex).
### Dynamics
GIMP supports the GIMP Paint Dynamics format which can be generated from
within GIMP.
### Patterns
GIMP supports the GIMP Pattern format (PAT, whose
[specification](specifications/pat.txt) is available for developers).
This format can be exported by GIMP itself.
Alternatively GIMP supports patterns from `GdkPixbuf` (TODO: get more
information?).
### Palettes
GIMP supports the GIMP Palette format which can be generated from within
GIMP.
### Gradients
GIMP supports the GIMP Gradient format (GGR, whose
[specification](specifications/ggr.txt) is available for developers)
which can be generated from within GIMP.
Alternatively GIMP supports the SVG Gradient format.
### Themes
### Icon themes
### Tool presets
## GIMP extensions (*.gex*)
## Continuous Integration
@ -226,10 +313,28 @@ When writing code, any core developer is expected to follow:
- GIMP's [coding style](/CODING_STYLE.md);
- the [directory structure](#directory-structure-of-gimp-source-tree)
- our [include rules](includes.txt)
- our [header file inclusion policy](includes.txt)
[GIMP's developer wiki](https://wiki.gimp.org/index.php/Main_Page) can
also contain various valuable resources.
### Newcomers
If this is your first time contributing to GIMP, you might be interested
by these [instructions on submitting
patches](https://gimp.org/bugs/howtos/submit-patch.html).
If you are unsure what to work on, this [list of bugs for
newcomers](https://gitlab.gnome.org/GNOME/gimp/-/issues?scope=all&state=opened&label_name[]=4.%20Newcomers)
might be a good start. It doesn't necessarily contain only bugs for
beginner developers. Some of them might be for experienced developers
who just don't know yet enough the codebase.
Nevertheless we often recommend to rather work on topics which you
appreciate, or even better: fixes for bugs you encounter or features you
want. These are the most self-rewarding contributions which will really
make you feel like developing on GIMP means developing for yourself.
### Core Contributors
### Maintainers
@ -254,6 +359,12 @@ Some of these duties include:
reason, especially when getting close to make the development branch
into the new stable branch. See also [os-support.txt](os-support.txt).
- Maintain [milestones](gitlab-milestones.txt).
- Maintain [NEWS](/NEWS) file. Any developer is actually encouraged to
update it when they do noteworthy changes, but this is the
maintainers' role to do the finale checks and make sure we don't miss
anything. The purpose of this rule is to make it as easy as possible
to make a GIMP release as looking in this file to write release notes
is much easier than reviewing hundreds of commits.
### Directory structure of GIMP source tree
@ -325,5 +436,66 @@ 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** |
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.
### Advanced concepts
#### XCF
The `XCF` format is the core image format of GIMP, which mirrors
features made available in GIMP. More than an image format, you may
consider it as a work or project format, as it is not made for finale
presentation of an artwork but for the work-in-progress processus.
Developers are welcome to read the [specifications of XCF](specifications/xcf.txt).
#### UI Framework
GIMP has an evolved GUI framework, with a toolbox, dockables, menus…
This [document describing how the GIMP UI framework functions and how it
is implemented](ui-framework.txt) might be of interest.
#### Contexts
GIMP uses a lot a concept of "contexts". We recommend reading more about
[how GimpContexts are used in GIMP](contexts.txt).
#### Undo
GIMP undo system can be challenging at times. This [quick overview of
the undo system](undo.txt) can be of interest as a first introduction.
#### Parasites
GIMP has a concept of "parasite" data which basically correspond to
persistent or semi-persistent data which can be attached to images or
items (layers, channels, paths) within an image. These parasites are
saved in the XCF format.
Parasites can also be attached globally to the GIMP session.
Parasite contents is format-free and you can use any parasite name,
nevertheless GIMP itself uses parasite so you should read the
[descriptions of known parasites](parasites.txt).
#### Metadata
GIMP supports Exif, IPTC and XMP metadata as well as various image
format-specific metadata. The topic is quite huge and complex, if not
overwhelming.
This [old document](exif-handling.txt) might be of interest (or maybe
not, it has not been recently reviewed and might be widely outdated; in
any case, it is not a complete document at all as we definitely do a lot
more nowadays). **TODO**: review this document and delete or update it
depending of whether it still makes sense.
#### Tagging
Various data in GIMP can be tagged across sessions.
This document on [how resource tagging in GIMP works](tagging.txt) may
be of interest.

29
devel-docs/commit-rules.txt
View File

@ -1,29 +0,0 @@
Commit Rules
============
This file describes rules and things to think about when creating GIMP
commits.
* Commit message format template:
modulename: Summary on one line
Detailed description that may span several paragraphs and
lines. Like this example description that is more than one
line. Focus on explaining _why_ the commit is needed.
or
Bug XXXXXX - Bug title
Detailed description that may span several paragraphs and
lines. Like this example description that is more than one
line. Focus on explaining _why_ the commit is needed.
Look at existing commit messages for examples.
* Keep NEWS up to date
Whenever you make a change that is worthy of being mentioned in the
NEWS file, update the NEWS file too. The purpose of this rule is to
make it as easy as possible to make a GIMP release.

1
devel-docs/submitting-patches.txt
View File

@ -1 +0,0 @@
See https://gimp.org/bugs/howtos/submit-patch.html for instructions