doc: add note about version ordering and OCaml REPL example

This follows a discussion in #6118

Signed-off-by: Mathieu Barbin <[email protected]>

README.md

@@ -180,7 +180,10 @@ that's not an option for you, you can use `git format-patch` and email us.
 
 ## Versioning
 
-The release cycle respects [Semantic Versioning](http://semver.org/).
+The release cycle of the opam binary respects [Semantic Versioning](http://semver.org/).
+Note however that the version ordering used for user packages managed by opam
+follows the Debian definition (more details in [this
+section](https://opam.ocaml.org/doc/Manual.html#version-ordering) of the user manual).
 
 ## Related Repositories
 

doc/pages/Manual.md

@@ -320,6 +320,14 @@ relational operators are `=`, `!=`, `<`, `<=`, `>` and `>=`, and their meaning
 is defined by Version Ordering. They always have higher priority than logical
 operators.
 
+Here is a full example:
+
+```
+"foo" { >= "3.12" } & ("bar" | "baz" { !(> "2" & < "3.5") & != "5.1" })
+```
+
+#### Version-ordering
+
 > <a id="version-ordering">**Version Ordering**</a> follows the basics of the
 > [Debian definition](https://www.debian.org/doc/debian-policy/ch-controlfields.html#s-f-Version).
 >
@@ -351,10 +359,13 @@ operators.
 > Here is an example of an ordered sequence: `~~`, `~`, `~beta2`, `~beta10`,
 > `0.1`, `1.0~beta`, `1.0`, `1.0-test`, `1.0.1`, `1.0.10`, `dev`, `trunk`.
 
-Here is a full example:
+For quick sanity checks, you can compare package versions using the OCaml REPL:
 
 ```
-"foo" { >= "3.12" } & ("bar" | "baz" { !(> "2" & < "3.5") & != "5.1" })
+#use "topfind";;
+#require "opam-core";;
+# OpamVersionCompare.compare "1.2.10" "1.2.9";;
+- : int = 1
 ```
 
 ### Variables

master_changes.md

@@ -156,6 +156,7 @@ users)
 ## Doc
   * Remove the ppa from the installation instructions on Ubuntu [#5988 @kit-ty-kate - fix #5987]
   * Fix pinning instructions in readme [#5946 @rjbou - fix #5945]
+  * Add a brief note about version ordering and an OCaml REPL example [#6119 @mbarbin]
 
 ## Security fixes