ovsdb-tool: Document database numbering scheme.

Prompted by an IRC discussion.

Signed-off-by: Ben Pfaff <blp@ovn.org>
Acked-by: Russell Bryant <russell@ovn.org>

2 files changed, 27 insertions, 9 deletions

diff --git a/ovsdb/ovsdb-tool.1.in b/ovsdb/ovsdb-tool.1.in
index a2f1f22ba..d01531e56 100644
--- a/ovsdb/ovsdb-tool.1.in
+++ b/ovsdb/ovsdb-tool.1.in
@@ -62,6 +62,29 @@ specified, the compacted version is written as a new file named
 omitted, then the compacted version of the database replaces \fIdb\fR
 in-place.
 .
+.SS "Version Management Commands"
+.PP
+An OVSDB schema has a schema version number, and an OVSDB database
+embeds a particular version of an OVSDB schema.  These version numbers
+take the form \fIx\fB.\fIy\fB.\fIz\fR, e.g. \fB1.2.3\fR.  The OVSDB
+implementation does not enforce a particular version numbering scheme,
+but schemas managed within the Open vSwitch project use the following
+approach.  Whenever the database schema is changed in a non-backward
+compatible way (e.g. deleting a column or a table), \fIx\fR is
+incremented (and \fIy\fR and \fIz\fR are reset to 0).  When the
+database schema is changed in a backward compatible way (e.g. adding a
+new column), \fIy\fR is incremented (and \fIz\fR is reset to 0).  When
+the database schema is changed cosmetically (e.g. reindenting its
+syntax), \fIz\fR is incremented.
+.
+.PP
+Some OVSDB databases and schemas, especially very old ones, do not
+have a version number.
+.
+.PP
+These commands work with different versions of OVSDB schemas and
+databases.
+.
 .IP "\fBconvert\fI db schema \fR[\fItarget\fR]"
 Reads \fIdb\fR, translating it into to the schema specified in
 \fIschema\fR, and writes out the new interpretation.  If \fItarget\fR
@@ -106,6 +129,8 @@ If \fIschema\fR or \fIdb\fR was created before schema checksums were
 introduced, then it will not have a checksum and this command
 will print a blank line.
 .
+.SS "Other Commands"
+.
 .IP "\fBquery\fI db transaction\fR"
 Opens \fIdb\fR, executes \fItransaction\fR on it, and prints the
 results.  The \fItransaction\fR must be a JSON array in the format of
diff --git a/vswitchd/vswitch.xml b/vswitchd/vswitch.xml
index b92b7c0b3..d10fc1def 100644
--- a/vswitchd/vswitch.xml
+++ b/vswitchd/vswitch.xml
@@ -501,15 +501,8 @@
 
       <column name="db_version">
         <p>
-          The database schema version number in the form
-          <code><var>major</var>.<var>minor</var>.<var>tweak</var></code>,
-          e.g. <code>1.2.3</code>.  Whenever the database schema is changed in
-          a non-backward compatible way (e.g. deleting a column or a table),
-          <var>major</var> is incremented.  When the database schema is changed
-          in a backward compatible way (e.g. adding a new column),
-          <var>minor</var> is incremented.  When the database schema is changed
-          cosmetically (e.g. reindenting its syntax), <var>tweak</var> is
-          incremented.
+          The database schema version number, e.g. <code>1.2.3</code>.  See
+          ovsdb-tool(1) for an explanation of the numbering scheme.
         </p>
 
         <p>