Guarantee a stable ordering with build metadata

Sorting any permutation of Version objects should always yield the same
result, even if those hold some build metadata.

To that end, the "precedence_key" is now used exclusively for sorting;
direct comparisons between Version objects still ignores the "build"
metadata, using a different precedence key.

For performance improvements, both precedence keys are cached.

Closes: #132

1 files changed, 10 insertions, 1 deletions

diff --git a/docs/reference.rst b/docs/reference.rst
index 6d1101b..b2946d9 100644
--- a/docs/reference.rst
+++ b/docs/reference.rst
@@ -130,7 +130,16 @@ Representing a version (the Version class)
         The actual value of the attribute is considered an implementation detail; the only
         guarantee is that ordering versions by their precedence_key will comply with semver precedence rules.
 
-        Note that the :attr:`~Version.build` isn't included in the precedence_key computatin.
+
+        .. warning::
+
+           .. versionchanged:: 2.10.0
+
+           The :attr:`~Version.build` is included in the precedence_key computation, but
+           only for ordering stability.
+           The only guarantee is that, for a given release of python-semanticversion, two versions'
+           :attr:`~Version.precedence_key` will always compare in the same direction if they include
+           build metadata; that ordering is an implementation detail and shouldn't be relied upon.
 
     .. attribute:: partial