From e62a2685661de1e3f2848fa1e5dd0a0f58d3359d Mon Sep 17 00:00:00 2001
From: Peter Dimov <pdimov@gmail.com>
Date: Wed, 5 Apr 2023 17:34:08 +0300
Subject: [PATCH] Update documentation

---
 doc/hash/notes.adoc  | 16 ++++++++++++++++
 doc/hash/recent.adoc | 17 ++++++++++++++---
 2 files changed, 30 insertions(+), 3 deletions(-)

diff --git a/doc/hash/notes.adoc b/doc/hash/notes.adoc
index a015967..59a98fc 100644
--- a/doc/hash/notes.adoc
+++ b/doc/hash/notes.adoc
@@ -55,6 +55,22 @@ to be templates constrained on e.g. `std::is_integral` or its moral
 equivalent. This causes types convertible to an integral to no longer
 match, avoiding the problem.
 
+== Hash Value Stability
+
+In general, the library does not promise that the hash values will stay
+the same from release to release (otherwise improvements would be
+impossible). However, historically values have been quite stable. Before
+release 1.81, the previous changes have been in 1.56 (a better
+`hash_combine`) and 1.78 (macOS-specific change to `hash_combine`.)
+
+Code should generally not depend on specific hash values, but for those
+willing to take the risk of occasional breaks due to hash value changes,
+the library now has a test that checks hash values for a number of types
+against reference values (`test/hash_reference_values.cpp`),
+whose https://github.com/boostorg/container_hash/commits/develop/test/hash_reference_values.cpp[version history]
+can be used as a rough guide to when hash values have changed, and for what
+types.
+
 == hash_combine
 
 The initial implementation of the library was based on Issue 6.18 of the
diff --git a/doc/hash/recent.adoc b/doc/hash/recent.adoc
index a98411b..94aa3b9 100644
--- a/doc/hash/recent.adoc
+++ b/doc/hash/recent.adoc
@@ -14,8 +14,10 @@ https://www.boost.org/LICENSE_1_0.txt
 * Added `is_tuple_like` and an overload of `hash_value` for
   tuple-like types.
 * Changed string hashing to use
-  https://github.com/pdimov/mulxp_hash[`mulxp1_hash`]. This
-  improves both quality and speed.
+  https://github.com/pdimov/mulxp_hash[`mulxp1_hash`],
+  improving both quality and speed. This changes the hash values
+  for string-like types (ranges of `char`, `signed char`,
+  `unsigned char`, `std::byte`, `char8_t`).
 
 == Boost 1.81.0
 
@@ -33,9 +35,18 @@ Major update.
 * Described structs and classes (those annotated with
   `BOOST_DESCRIBE_STRUCT` or `BOOST_DESCRIBE_CLASS`) are now
   supported out of the box.
-* `hash_combine` has been improved.
+* `hash_combine` has been improved. This changes the hash values
+  of composite (container and tuple) types and of scalar types
+  bigger than `size_t`.
 * The performance (and quality, as a result of the above change)
   of string hashing has been improved. `boost::hash` for strings
   now passes SMHasher in 64 bit mode.
 * The documentation has been substantially revised to reflect
   the changes.
+
+== Boost 1.78.0
+
+* Fixed `hash_combine` so that its behavior no longer depends
+  on whether `size_t` is the exact same type as `boost::uint64_t`
+  (which wasn't the case on macOS). This changes the hash values
+  of composite (container and tuple) types on macOS.