Document major and minor SDFormat version numbers (#1065)

Signed-off-by: Steve Peters <scpeters@openrobotics.org>
gazebosim · Jul 7, 2022 · 2f13983 · 2f13983
1 parent 9fc2e5f
commit 2f13983
Show file tree

Hide file tree

Showing 5 changed files with 45 additions and 5 deletions.
diff --git a/sdf/1.3/root.sdf b/sdf/1.3/root.sdf
@@ -2,7 +2,15 @@
   <description>SDFormat base element.</description>
 
   <attribute name="version" type="string" default="1.3" required="1">
-    <description>Version number of the SDFormat specification.</description>
+    <description>
+        Version number of the SDFormat specification, consisting of major
+        and minor versions delimited by a `.` character.
+        A major version bump is required if older versions cannot be
+        automatically converted to this version.
+        A minor version bump is required when there are breaking changes that
+        can be handled by the automatic conversion functionality encoded in the
+        `*.convert` files.
+    </description>
   </attribute>
 
   <include filename="world.sdf" required="*"/>

diff --git a/sdf/1.4/root.sdf b/sdf/1.4/root.sdf
@@ -2,7 +2,15 @@
   <description>SDFormat base element.</description>
 
   <attribute name="version" type="string" default="1.4" required="1">
-    <description>Version number of the SDFormat specification.</description>
+    <description>
+        Version number of the SDFormat specification, consisting of major
+        and minor versions delimited by a `.` character.
+        A major version bump is required if older versions cannot be
+        automatically converted to this version.
+        A minor version bump is required when there are breaking changes that
+        can be handled by the automatic conversion functionality encoded in the
+        `*.convert` files.
+    </description>
   </attribute>
 
   <include filename="world.sdf" required="*"/>

diff --git a/sdf/1.5/root.sdf b/sdf/1.5/root.sdf
@@ -2,7 +2,15 @@
   <description>SDFormat base element.</description>
 
   <attribute name="version" type="string" default="1.5" required="1">
-    <description>Version number of the SDFormat specification.</description>
+    <description>
+        Version number of the SDFormat specification, consisting of major
+        and minor versions delimited by a `.` character.
+        A major version bump is required if older versions cannot be
+        automatically converted to this version.
+        A minor version bump is required when there are breaking changes that
+        can be handled by the automatic conversion functionality encoded in the
+        `*.convert` files.
+    </description>
   </attribute>
 
   <include filename="world.sdf" required="*"/>

diff --git a/sdf/1.6/root.sdf b/sdf/1.6/root.sdf
@@ -2,7 +2,15 @@
   <description>SDFormat base element that can include 0-N models, actors, lights, and/or worlds. A user of multiple worlds could run parallel instances of simulation, or offer selection of a world at runtime.</description>
 
   <attribute name="version" type="string" default="1.6" required="1">
-    <description>Version number of the SDFormat specification.</description>
+    <description>
+        Version number of the SDFormat specification, consisting of major
+        and minor versions delimited by a `.` character.
+        A major version bump is required if older versions cannot be
+        automatically converted to this version.
+        A minor version bump is required when there are breaking changes that
+        can be handled by the automatic conversion functionality encoded in the
+        `*.convert` files.
+    </description>
   </attribute>
 
   <include filename="world.sdf" required="*"/>

diff --git a/sdf/1.7/root.sdf b/sdf/1.7/root.sdf
@@ -2,7 +2,15 @@
   <description>SDFormat base element that can include 0-N models, actors, lights, and/or worlds. A user of multiple worlds could run parallel instances of simulation, or offer selection of a world at runtime.</description>
 
   <attribute name="version" type="string" default="1.7" required="1">
-    <description>Version number of the SDFormat specification.</description>
+    <description>
+        Version number of the SDFormat specification, consisting of major
+        and minor versions delimited by a `.` character.
+        A major version bump is required if older versions cannot be
+        automatically converted to this version.
+        A minor version bump is required when there are breaking changes that
+        can be handled by the automatic conversion functionality encoded in the
+        `*.convert` files.
+    </description>
   </attribute>
 
   <include filename="world.sdf" required="*"/>