diff --git a/devel-docs/Makefile.am b/devel-docs/Makefile.am
index d5ae510f99..0484d124fe 100644
--- a/devel-docs/Makefile.am
+++ b/devel-docs/Makefile.am
@@ -17,26 +17,27 @@ SUBDIRS = \
$(app)
EXTRA_DIST = \
- ChangeLog \
- README \
- README.gtkdoc \
- contexts.txt \
- debug-plug-ins.txt \
- exif-handling.txt \
- gbr.txt \
- ggr.txt \
- gih.txt \
- gpb.txt \
- includes.txt \
- parasites.txt \
- pat.txt \
- release-howto.txt \
- structure.xml \
- submitting-patches.txt \
- tagging.txt \
- ui-framework.txt \
- undo.txt \
- vbr.txt \
+ ChangeLog \
+ README \
+ README.gtkdoc \
+ contexts.txt \
+ debug-plug-ins.txt \
+ exif-handling.txt \
+ gbr.txt \
+ ggr.txt \
+ gih.txt \
+ gpb.txt \
+ includes.txt \
+ parasites.txt \
+ pat.txt \
+ gtkbuilder-porting-guide.txt \
+ release-howto.txt \
+ structure.xml \
+ submitting-patches.txt \
+ tagging.txt \
+ ui-framework.txt \
+ undo.txt \
+ vbr.txt \
xcf.txt
diff --git a/devel-docs/gtkbuilder-porting-guide.txt b/devel-docs/gtkbuilder-porting-guide.txt
new file mode 100644
index 0000000000..2eb2c717f4
--- /dev/null
+++ b/devel-docs/gtkbuilder-porting-guide.txt
@@ -0,0 +1,150 @@
+gtkbuilder-porting-guide.txt
+============================
+
+This document describes some tips and rules for how to port UI code
+written with GTK+ and C to GtkBuilder + Glade.
+
+
+
+Overview
+--------
+
+1. Locate code to port
+2. Start a new UI file with Glade
+3. Systematically convert the code to Glade
+4. Construct UI with GtkBuilder and do setup of widgets
+5. Add .ui file to build system
+6. Test
+7. Enjoy less UI C code
+8. Troubleshooting
+
+
+
+Locate code to port
+-------------------
+
+Look for code that looks like this:
+
+ // Create a widget and add to hierarchy
+ widget = gtk_some_widget_new (some_params);
+ gtk_some_container_add (container, widget)
+ gtk_widget_show (widget);
+
+ // Repeat...
+
+
+
+Start a new UI file with Glade
+------------------------------
+
+Start glade-3. Pick project file format 'GtkBuilder' (not
+'Libglade'). For maximum compatibility, use the minimal gtk+ catalog
+possible. The file extension shall be .ui. Look where other files are
+put and how they are named.
+
+
+
+Systematically convert the code to Glade
+----------------------------------------
+
+Go through the code that you want to convert line by line and add
+widgets in Glade as you remove lines. For example:
+
+ main_vbox = gtk_vbox_new (FALSE, 12);
+ gtk_container_set_border_width (GTK_CONTAINER (main_vbox), 12);
+ gtk_container_add (GTK_CONTAINER (dialog_vbox),
+ main_vbox);
+ gtk_widget_show (main_vbox);
+
+is replaced by
+
+
+
+in the UI declaration produced by Glade.
+
+
+
+Construct UI with GtkBuilder and do setup of widgets
+----------------------------------------------------
+
+The code to construct the UI will look something like this:
+
+ builder = gtk_builder_new ();
+ ui_file = g_build_filename (gimp_data_directory (),
+ "ui/plug-ins/plug-in-file-gif-save.ui",
+ NULL);
+ if (! gtk_builder_add_from_file (builder, ui_file, &error))
+ g_printerr (_("Error loading UI file '%s':\n%s"),
+ ui_file, error ? error->message : "???");
+ g_free (ui_file);
+
+and then you do setup of widgets using:
+
+ widget = GTK_WIDGET (gtk_builder_get_object (builder, "widget-name"));
+ gtk_widget_whatever (widget, params);
+
+Look in plug-ins/common/file-gif-save.c for helper function you can
+use for some tricky widgets.
+
+
+
+Add .ui file to build system
+----------------------------
+
+The UI declarations are installed as data files, see
+plug-ins/ui/Makefile.am for example, and it needs to be added to
+POTFILES.in for translations.
+
+
+
+Test
+----
+
+When you're done, make sure
+
+1. that translations still work. If they don't, maybe you forgot to
+add the UI file to the relevant POTFILES.in or maybe you changed
+strings, for example by adding markup. In the latter case, use pango
+text styles instead of markup (use GKT+ 2.16 UI files).
+
+2. that mnemonics still work, in particular when the mnemonic is not
+on the widget to be activated. For e.g. labels you need to explicitly
+assign a widget that will be actiated when the label mnemonic is
+pressed.
+
+3. that the spacing and other layout detals are still correct.
+
+
+
+Enjoy less UI C code
+--------------------
+
+Enjoy!
+
+
+
+Troubleshooting
+---------------
+
+If your GtkComboBox doesn't draw any items it's probably because it
+doesn't have a cell renderer. Appearently there is no UI to add one in
+GLade-3, so add it manually in the UI file, see the GTK+ doc for
+GtkCellLayout; this is what you need to add:
+
+