docs: Add a contribution guide

Outline a contribution workflow, and how GdkPixbuf is logically split.

1 files changed, 141 insertions, 0 deletions

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
new file mode 100644
index 000000000..4f2751485
--- /dev/null
+++ b/CONTRIBUTING.md
@@ -0,0 +1,141 @@
+Contributing to GdkPixbuf
+=========================
+
+### Requirements
+
+If you wish to contribute to GdkPixbuf you will need to install the
+appropriate development tools for your operating system, including:
+
+ - Python 3.x
+ - Meson
+ - Ninja
+ - Gettext
+ - a C99 compatible compiler
+
+### Cloning and building
+
+You can start by cloning the Git repository:
+
+```sh
+$ git clone https://gitlab.gnome.org/GNOME/gdk-pixbuf.git
+$ cd gdk-pixbuf
+```
+
+Then you should build GdkPixbuf locally:
+
+```sh
+$ meson _build .
+$ cd _build
+$ ninja
+```
+
+### Development
+
+Once you built GdkPixbuf, you should create a new branch in order
+to work on your bug fix, or your feature, undisturbed:
+
+```sh
+$ git checkout -b my-amazing-feature
+[ work work work ... ]
+```
+
+You should run the test suite locally, to verify you are not introducing a
+regression; if you are fixing a bug, you should also add a test case to
+verify that the fix works and to avoid future regressions; if you are
+introducing a new feature, you should write a comprehensive test suite:
+
+```sh
+$ cd _build
+$ meson test
+```
+
+When introducing a new feature or new API, you should document it using the
+[gtk-doc](https://developer.gnome.org/gtk-doc-manual/stable/) format. You
+can build the GdkPixbuf API reference locally by enabling the `docs`
+configuration option and building the `gdk-pixbuf-doc` target:
+
+```sh
+$ cd _build
+$ meson configure -Ddocs=true
+$ ninja
+$ ninja gdk-pixbuf-doc
+```
+
+### Contributing
+
+Once you're done with your work, you should commit it, push it to a remote
+repository, and open a Merge Request against the GdkPixbuf upstream
+repository. Follow the [GitLab workflow page](https://wiki.gnome.org/GitLab/)
+on the GNOME wiki for further instructions.
+
+Once you opened a Merge Request, the GdkPixbuf maintainers will review your
+contribution.
+
+## Project layout
+
+```
+├── build-aux
+├── contrib
+│   └── gdk-pixbuf-xlib
+├── docs
+│   └── reference
+│       └── gdk-pixbuf
+├── gdk-pixbuf
+│   └── pixops
+├── m4
+├── po
+├── tests
+│   └── test-images
+│       ├── fail
+│       ├── randomly-modified
+│       └── reftests
+│           └── tga
+└── thumbnailer
+```
+
+ - `build-aux`: Ancillary files, necessary to build GdkPixbuf
+ - `contrib`: Additional functionality outside the main GdkPixbuf API
+  - `gdk-pixbuf-xlib`: Xlib integration API; this library is considered
+    deprecated, and should not be used in newly written code
+ - `docs/reference/gdk-pixbuf`: The GdkPixbuf API reference
+ - `gdk-pixbuf`: The core GdkPixbuf source
+  - `pixops`: Platform-specific code for pixel operations
+ - `po`: Localization files
+ - `tests`: Test suite
+  - `test-images`: Reference images for the test suite
+ - `thumbnailer`: Helper binary for generating thumbnails with GdkPixbuf
+
+### Architecture
+
+GdkPixbuf is divided into logical sections:
+
+ - Core: the [GdkPixbuf][gdkpixbuf-api-core] object and its properties
+ - Construction: [creating][gdkpixbuf-api-ctor] a new GdkPixbuf instance from a buffer
+ - I/O: [Loading][gdkpixbuf-api-load] and [Saving][gdkpixbuf-api-save] image
+   data in different formats
+ - Image transformations: [Scaling and compositing][gdkpixbuf-api-ops] image
+   data inside GdkPixbuf instances
+ - The [GdkPixbuf loader][gdkpixbuf-api-loaders] API, for incremental
+   asynchronous loading of image data in a GdkPixbuf
+ - The [loadable module interface][gdkpixbuf-api-module] for writing out of
+   tree image loaders
+ - The [animated image][gdkpixbuf-api-animation] API, for image formats
+   that support animations
+
+### Notes
+
+GdkPixbuf is a library with a long history, and it has been incrementally
+modified over years, so it may retain some older coding practices alongside
+newer ones.
+
+As it deals with loading image data into user processes, it's also important
+to note that GdkPixbuf must always deal with potential security issues.
+
+[gdkpixbuf-api-core]: https://developer.gnome.org/gdk-pixbuf/stable/gdk-pixbuf-The-GdkPixbuf-Structure.html
+[gdkpixbuf-api-ctor]: https://developer.gnome.org/gdk-pixbuf/stable/gdk-pixbuf-Image-Data-in-Memory.html
+[gdkpixbuf-api-load]: https://developer.gnome.org/gdk-pixbuf/stable/gdk-pixbuf-File-Loading.html
+[gdkpixbuf-api-save]: https://developer.gnome.org/gdk-pixbuf/stable/gdk-pixbuf-File-saving.html
+[gdkpixbuf-api-ops]: https://developer.gnome.org/gdk-pixbuf/stable/gdk-pixbuf-Scaling.html
+[gdkpixbuf-api-loader]: https://developer.gnome.org/gdk-pixbuf/stable/GdkPixbufLoader.html
+[gdkpixbuf-api-module]: https://developer.gnome.org/gdk-pixbuf/stable/gdk-pixbuf-Module-Interface.html
+[gdkpixbuf-api-animation]: https://developer.gnome.org/gdk-pixbuf/stable/gdk-pixbuf-Animations.html