Update upgrading notes [ci skip]
@@ -190,4 +190,31 @@ installed, which provides the relevant tables.
## Notes about upgrading from v3.0 {#upgrading}
-<!-- TODO: this could just be a bullet-point list mentioning stuff like the spacy_version, vectors initialization etc. -->
+### Pipeline package version compatibility {#version-compat}
+
+> #### Using legacy implementations
+>
+> In spaCy v3, you'll still be able to load and reference legacy implementations
+> via [`spacy-legacy`](https://github.com/explosion/spacy-legacy), even if the
+> components or architectures change and newer versions are available in the
+> core library.
+
+When you're loading a pipeline package trained with spaCy v3.0, you will see a
+warning telling you that the pipeline may be incompatible. This doesn't
+necessarily have to be true, but we recommend running your pipelines against
+your test suite or evaluation data to make sure there are no unexpected results.
+If you're using one of the [trained pipelines](/models) we provide, you should
+run [`spacy download`](/api/cli#download) to update to the latest version. To
+see an overview of all installed packages and their compatibility, you can run
+[`spacy validate`](/api/cli#validate).
+
+If you've trained your own custom pipeline and you've confirmed that it's still
+working as expected, you can update the spaCy version requirements in the
+[`meta.json`](/api/data-formats#meta):
+
+```diff
+- "spacy_version": ">=3.0.0,<3.1.0",
++ "spacy_version": ">=3.0.0,<3.2.0",
+```
+
+<!-- TODO: vectors initialization and anything else we want to mention -->
