From d6b059ec740a6affce9a069f1210d161068317e3 Mon Sep 17 00:00:00 2001
From: Tom Lane <tgl@sss.pgh.pa.us>
Date: Wed, 8 Mar 2017 17:01:13 -0500
Subject: [PATCH] Document intentional violations of header inclusion policy.

Although there are good reasons for our policy of including postgres.h
as the first #include in every .c file, never from .h files, there are
two places where it seems expedient to violate the policy because the
alternative is to modify externally-supplied .c files.  (In the case
of the regexp library, the idea that it's externally-supplied is kind
of at odds with reality, but I haven't entirely given up hope that it
will become a standalone project some day.)  Add some comments to make
it explicit that this is a policy violation and provide the reasoning.

In passing, move #include "miscadmin.h" out of regcomp.c and into
regcustom.h, which is where it should be if we're taking this reasoning
seriously at all.

Discussion: https://postgr.es/m/CAEepm=2zCoeq3QxVwhS5DFeUh=yU6z81pbWMgfOB8OzyiBwxzw@mail.gmail.com
Discussion: https://postgr.es/m/11634.1488932128@sss.pgh.pa.us
---
 src/backend/regex/regcomp.c   | 2 --
 src/include/regex/regcustom.h | 9 +++++++++
 src/include/snowball/header.h | 5 +++++
 3 files changed, 14 insertions(+), 2 deletions(-)

diff --git a/src/backend/regex/regcomp.c b/src/backend/regex/regcomp.c
index ed95474b3f0..0834ae6e064 100644
--- a/src/backend/regex/regcomp.c
+++ b/src/backend/regex/regcomp.c
@@ -34,8 +34,6 @@
 
 #include "regex/regguts.h"
 
-#include "miscadmin.h"			/* needed by rcancelrequested/rstacktoodeep */
-
 /*
  * forward declarations, up here so forward datatypes etc. are defined early
  */
diff --git a/src/include/regex/regcustom.h b/src/include/regex/regcustom.h
index 04a1893c806..82c9e2fad81 100644
--- a/src/include/regex/regcustom.h
+++ b/src/include/regex/regcustom.h
@@ -29,6 +29,13 @@
  */
 
 /* headers if any */
+
+/*
+ * It's against Postgres coding conventions to include postgres.h in a
+ * header file, but we allow the violation here because the regexp library
+ * files specifically intend this file to supply application-dependent
+ * headers, and are careful to include this file before anything else.
+ */
 #include "postgres.h"
 
 #include <ctype.h>
@@ -47,6 +54,8 @@
 
 #include "mb/pg_wchar.h"
 
+#include "miscadmin.h"			/* needed by rcancelrequested/rstacktoodeep */
+
 
 /* overrides for regguts.h definitions, if any */
 #define FUNCPTR(name, args) (*name) args
diff --git a/src/include/snowball/header.h b/src/include/snowball/header.h
index 9501f77ac14..d8be02ee609 100644
--- a/src/include/snowball/header.h
+++ b/src/include/snowball/header.h
@@ -22,6 +22,11 @@
 #ifndef SNOWBALL_HEADR_H
 #define SNOWBALL_HEADR_H
 
+/*
+ * It's against Postgres coding conventions to include postgres.h in a
+ * header file, but we allow the violation here because the alternative is
+ * to modify the machine-generated .c files provided by the Snowball project.
+ */
 #include "postgres.h"
 
 /* Some platforms define MAXINT and/or MININT, causing conflicts */
-- 
GitLab