add section about equals()/hashCode()

Author: gavinking

documentation/src/main/asciidoc/reference/introduction.adoc

@@ -413,6 +413,44 @@ values!
 When you use Hibernate Reactive in Quarkus, these requirements are relaxed,
 and you can use public fields instead of getters and setters if you prefer.
 
+=== `equals()` and `hashCode()`
+
+Entity classes should override `equals()` and `hashCode()`. People new to
+Hibernate or JPA are often confused by exactly which fields should be
+included in the `hashCode()`, so please keep the following principles in
+mind:
+
+- You should not include mutable fields in the hashcode, since that would
+  require rehashing any collection containing the entity whenever the field
+  is mutated.
+- It's not completely wrong to include a generated identifier (surrogate
+  key) in the hashcode, but since the identifier is not generated until
+  the entity instance is made persistent, you must take great care to not
+  add it to any hashed collection before the identifier is generated. We
+  therefore advise against including any database-generated field in the
+  hashcode.
+
+It's OK to include any immutable, non-generated field in the hashcode.
+
+TIP: We therefore recommend identifying a _natural key_ for each entity,
+that is, a combination of fields that uniquely identifies an instance of
+the entity, from the perspective of the data model of the program. The
+business key should correspond to a unique constraint on the database,
+and to the fields which are included in `equals()` and `hashCode()`.
+
+That said, an implementation of `equals()` and `hashCode()` based on the
+generated identifier of the entity can work _if you're careful_.
+
+IMPORTANT: If you can't identify a natural key, it might be a sign that
+you need to think more carefully about some aspect of your data model.
+If an entity doesn't have a meaningful unique key, then it's impossible
+to say what event or object it represents in the "real world" outside
+your program.
+
+Note that even when you've identified a natural key, we still recommend
+the use of a generated surrogate key in foreign keys, since this makes
+your data model _much_ easier to change.
+
 === Identifier generation
 
 One area where the functionality of Hibernate Reactive diverges from plain