Edit the 4.0.0 changelog and migration guide against 3.x

doc/guide/query-examples.md

@@ -1026,7 +1026,7 @@ The query above will insert a pet named `I am the dog of Jennifer whose id is 52
 
 A `#ref` to a new model (a model without an id), or a `#ref{}` to the id of a new model, needs the id that the database gives the model when the graph inserts it. If the graph doesn't write that model, e.g. because the `noInsert` option skips it, or because it sits below a model that `upsertGraph` ignores because of the `noRelate` option or removes because of `#delete` or `#unrelate`, such a reference throws a `ValidationError` of type `InvalidGraph` before anything is written. A plain `#ref` to a model with an id relates the existing row, and a `#ref{}` to any other property reads the model as the graph gives it, so neither needs the model to be written. Below a model that `noInsert` skips, only the branches that references of written models point into are written, without the skipped model.
 
-`upsertGraph` writes the models below rows that it relates into a `HasManyRelation` or `HasOneRelation` from another owner after the rest of the graph (see [graph upserts](#graph-upserts)), so the rest of the graph can't `#ref` new models below them, nor read their ids with `#ref{}`. The references of these models are checked once the rest of the graph is written, before they are written themselves.
+`upsertGraph` loads and writes the models below rows that it relates into a `HasManyRelation` or `HasOneRelation` from another owner together with the rest of the graph, with their relations read where the rows end up, so references can point to new models below them like to any other model.
 
 Existing rows can be related to newly inserted rows by using the `relate` option. `relate` can be `true` in which case all models in the graph that have an identifier get related. `relate` can also be an array of relation paths like `['children', 'children.movies.actors']` in which case only objects in those paths get related even if they have an idetifier.