0001-Added-paragraph-about-the-distinction-between-extens.patch

From 03fa593a46f1dae0a8e83b4bccd6dea51e2c102c Mon Sep 17 00:00:00 2001
From: Daniele Varrazzo <daniele.varrazzo@gmail.com>
Date: Thu, 28 Apr 2011 14:02:08 +0100
Subject: [PATCH] Added paragraph about the distinction between extension version and patch level.

---
 doc/src/sgml/extend.sgml |   14 ++++++++++++++
 1 files changed, 14 insertions(+), 0 deletions(-)

diff --git a/doc/src/sgml/extend.sgml b/doc/src/sgml/extend.sgml
index 4ca17ef..ad26f5a 100644
--- a/doc/src/sgml/extend.sgml
+++ b/doc/src/sgml/extend.sgml
@@ -767,6 +767,20 @@ SELECT pg_catalog.pg_extension_config_dump('my_config', 'WHERE NOT standard_entr
     </para>
 
     <para>
+     Note that version names are only meant to give an identity to the set of
+     objects in the database schema and should not be used to track outside
+     objects such as shared libraries or data files.  Specifically, if the
+     extension has a concept of <firstterm>revision</> or <firstterm>patch
+     level</> (maybe loaded with semantic meaning such as revisions order or
+     release status), setting a version equal to the patch level is
+     discouraged as it would require a large number of mostly equal (or empty)
+     upgrade scripts. For example, if a bug is found in the C code of the
+     extension <literal>foo</> version <literal>1.0</> you may want to release
+     a revision <literal>1.0.1</> but you should leave the version as
+     <literal>1.0</> if no object in the database schema is changed.
+    </para>
+
+    <para>
      Sometimes it is useful to provide <quote>downgrade</> scripts, for
      example <literal>foo--1.1--1.0.sql</> to allow reverting the changes
      associated with version <literal>1.1</>.  If you do that, be careful
-- 
1.7.1