diff --git a/HACKING b/HACKING
index 20dc743c3..e04e0dcdd 100644
--- a/HACKING
+++ b/HACKING
@@ -33,4 +33,5 @@ Note that autogen.sh runs configure for you.  If you wish to pass
 options like --prefix=/usr to configure you can give those options
 to autogen.sh and they will be passed on to configure.
 
-For information about submitting patches see the README.commits file.
+For information about submitting patches see the README.commits file. For
+information about major design decisions, see the README.rationale file.
diff --git a/Makefile.am b/Makefile.am
index 40e5cd5bc..a1c9c33a0 100644
--- a/Makefile.am
+++ b/Makefile.am
@@ -40,6 +40,7 @@ EXTRA_DIST += 			\
 	sanity_check		\
 	README.commits		\
 	README.in		\
+	README.rationale	\
 	INSTALL.in		\
 	README.win32		\
 	HACKING			\
diff --git a/README.rationale b/README.rationale
new file mode 100644
index 000000000..85a3dfd59
--- /dev/null
+++ b/README.rationale
@@ -0,0 +1,10 @@
+This file documents various major decisions which affect GLib development,
+giving a brief rationale of each decision, plus a link to further discussion.
+
+
+ * Compiler attributes: https://bugzilla.gnome.org/show_bug.cgi?id=113075#c46
+
+   GLib uses GIR annotations instead of compiler attributes. They are tidier,
+   already supported by GLib and GNOME tools, and accomplish the same task as
+   compiler attributes. GLib does not provide macros for attributes like
+   nonnull because it would not use them.