Re: Install extensions using update scripts (was Re: Remove superuser() checks from pgstattuple)

I wrote:
> Still no SGML doc updates.

And here's a doc addition.

            regards, tom lane

diff --git a/doc/src/sgml/extend.sgml b/doc/src/sgml/extend.sgml
index df88380..1c8c420 100644
*** a/doc/src/sgml/extend.sgml
--- b/doc/src/sgml/extend.sgml
*************** SELECT * FROM pg_extension_update_paths(
*** 885,890 ****
--- 885,927 ----
      </para>
     </sect2>

+    <sect2>
+     <title>Installing Extensions using Update Scripts</title>
+
+     <para>
+      An extension that has been around for awhile will probably exist in
+      several versions, for which the author will need to write update scripts.
+      For example, if you have released a <literal>foo</> extension in
+      versions <literal>1.0</>, <literal>1.1</>, and <literal>1.2</>, there
+      should be update scripts <filename>foo--1.0--1.1.sql</>
+      and <filename>foo--1.1--1.2.sql</>.
+      Before <productname>PostgreSQL</> 10, it was necessary to create new
+      script files <filename>foo--1.1.sql</> and <filename>foo--1.2.sql</>
+      containing the same changes, or else the newer versions could not be
+      installed directly, only by installing <literal>1.0</> and then updating.
+      Now, <command>CREATE EXTENSION</> can do that automatically —
+      for example, if only the script
+      files <filename>foo--1.0.sql</>, <filename>foo--1.0--1.1.sql</>,
+      and <filename>foo--1.1--1.2.sql</> are available then a request to
+      install version <literal>1.2</> is honored by running those three scripts
+      in sequence.  (As with update requests, if multiple pathways are
+      available then the shortest is preferred.)
+      Arranging an extension's script files in this style can reduce the amount
+      of maintenance effort needed to produce small updates.
+     </para>
+
+     <para>
+      If you use secondary (version-specific) control files with an extension
+      maintained in this style, keep in mind that each version needs a control
+      file even if it has no stand-alone installation script, as that control
+      file will determine how the implicit update to that version is performed.
+      For example, if <filename>foo--1.0.control</> specifies <literal>requires
+      = 'bar'</> but <literal>foo</>'s other control files do not, the
+      extension's dependency on <literal>bar</> will be dropped when updating
+      from <literal>1.0</> to another version.
+     </para>
+    </sect2>
+
     <sect2 id="extend-extensions-example">
      <title>Extension Example</title>