diff --git a/README.md b/README.md
index 9b6804387de..ed32052e0bd 100644
--- a/README.md
+++ b/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
 
diff --git a/doc/pages/Manual.md b/doc/pages/Manual.md
index 15f3229a441..1dcdf4d0cbc 100644
--- a/doc/pages/Manual.md
+++ b/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
diff --git a/master_changes.md b/master_changes.md
index 950a52af988..98e8852c143 100644
--- a/master_changes.md
+++ b/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