v31-0005-Doc-Add-Collation-Versions-section.patch

From 1fa864c34289a26cf7acce5f491243242bc59570 Mon Sep 17 00:00:00 2001
From: Thomas Munro <thomas.munro@gmail.com>
Date: Wed, 11 Mar 2020 15:01:23 +1300
Subject: [PATCH v31 5/5] Doc: Add Collation Versions section.

Supply a brief introduction to collation version concepts.

Author: Thomas Munro <thomas.munro@gmail.com>
Reviewed-by: Julien Rouhaud <rjuju123@gmail.com>
Discussion: https://postgr.es/m/CAEepm%3D0uEQCpfq_%2BLYFBdArCe4Ot98t1aR4eYiYTe%3DyavQygiQ%40mail.gmail.com
---
 doc/src/sgml/charset.sgml | 35 +++++++++++++++++++++++++++++++++++
 1 file changed, 35 insertions(+)

diff --git a/doc/src/sgml/charset.sgml b/doc/src/sgml/charset.sgml
index 2745b44417..c450febe00 100644
--- a/doc/src/sgml/charset.sgml
+++ b/doc/src/sgml/charset.sgml
@@ -948,6 +948,41 @@ CREATE COLLATION ignore_accents (provider = icu, locale = 'und-u-ks-level1-kc-tr
     </tip>
    </sect3>
   </sect2>
+
+  <sect2 id="collation-versions">
+   <title>Collation Versions</title>
+
+   <para>
+    The ordering defined by a collation is not necessarily fixed over time.
+    If a collation changes for any reason, persistent data structures such as
+    b-trees that depend on a stable ordering of text might be corrupted.
+    <productname>PostgreSQL</productname> defends against this by recording
+    the current version of each referenced collation for any index that
+    depends on it in the
+    <link linkend="catalog-pg-depend"><structname>pg_depend</structname></link>
+    catalog, if the collation provider makes it available.  If the provider
+    later begins to report a different version, a warning will be issued
+    when the index is accessed, until either the <xref linkend="sql-reindex"/>
+    or the <xref linkend="sql-alterindex"/> command is used to update the
+    version.
+   </para>
+   <para>
+    Version information is available for collations from the
+    <literal>icu</literal> provider on all operating systems.  For the
+    <literal>libc</literal> provider, versions are currently only available
+    on systems using the GNU C library (most Linux systems) and Windows.
+   </para>
+
+   <note>
+    <para>
+     When using the GNU C library for collations, the C library's version
+     is used as a proxy for the collation version.  Many Linux distributions
+     change collation definitions only when upgrading the C library, but this
+     approach is imperfect as maintainers are free to back-port newer
+     collation definitions to older C library releases.
+    </para>
+   </note>
+  </sect2>
  </sect1>
 
  <sect1 id="multibyte">
-- 
2.20.1