add upgrade guide

README.md

@@ -20,6 +20,10 @@ JVector vs Lucene searching the Deep100M dataset (about 35GB of vectors and 25GB
 JVector scales updates linearly to at least 32 threads:
 ![Screenshot from 2023-09-14 18-05-15](https://github.com/jbellis/jvector/assets/42158/f0127bfc-6c45-48b9-96ea-95b2120da0d9)
 
+## Upgrading from 1.0.x to 2.0.x
+
+See [UPGRADING.md](./UPGRADING.md).
+
 ## JVector basics
 Adding to your project. Replace `${latest-version}` with ![Maven Central](https://img.shields.io/maven-central/v/io.github.jbellis/jvector?color=green). Example `<version>1.0.1</version>`:
 

UPGRADING.md

@@ -0,0 +1,21 @@
+# Upgrading from 1.0.x to 2.0.x
+
+## New features
+
+- In-graph deletes are supported through `GraphIndexBuilder.markNodeDeleted`.  Deleted nodes
+  are removed when `GraphIndexBuilder.cleanup` is called (which is not threadsafe wrt other concurrent changes).
+  To write a graph with deleted nodes to disk, the a `Map` must be supplied indicating what ordinals
+  to change the remaining node ids to -- on-disk graphs may not contain "holes" in the ordinal sequence.
+- `GraphSearcher.search` now has an experimental overload that takes a
+  `float threshold` parameter that may be used instead of topK; (approximately) all the nodes with simlarities greater than the given threshold will be returned.
+
+## Primary API changes
+
+- `GraphIndexBuilder.complete` is now `cleanup`.
+- The `Bits` parameter to `GraphSearcher.search` is no longer nullable;
+  pass `Bits.ALL` instead of `null` to indicate that all ordinals are acceptable.
+
+## Other changes to public classes
+
+- `NeighborQueue`, `NeighborArray`, and `NeighborSimilarity` have been renamed to
+  `NodeQueue`, `NodeArray`, and `NodeSimilarity`, respectively.