add migration notes to docs (#3432)

* add migration notes to docs

* move migration documentation

* fix config name

docs/index.rst

@@ -23,6 +23,7 @@ Nuts documentation
 
     pages/deployment/domain.rst
     pages/deployment/configuration.rst
+    pages/deployment/migration.rst
     pages/deployment/recommended-deployment.rst
     pages/deployment/docker.rst
     pages/deployment/storage.rst

docs/pages/deployment/migration.rst

@@ -0,0 +1,39 @@
+.. _nuts-node-migration:
+
+Migrating from v5 to v6
+************************
+
+Nuts node v6 runs several migrations on startup for DID documents that are managed by the node, namely:
+
+1. Remove controllers and add self-control to ``did:nuts`` documents,
+2. Import ``did:nuts`` documents into the new SQL database under a ``subject`` with the same name, and
+3. Add a ``did:web`` document with the same services to the same ``subject``.
+
+**Migration: convert did:nuts to self-control**
+Requires ``vdr.didmethods`` to contain ``nuts``.
+
+Previously, DID documents could either by under self-control or under control of another DID as was recommended for vendor and care organisation, respectively.
+In the new situation a user manages ``subject``s, and the node manages all DIDs under the ``subject``.
+To reduce complexity and allow future adoption of other did methods, all documents will be under self-control from v6.
+
+**Migration: convert did:nuts to subject**
+Requires ``vdr.didmethods`` to contain ``nuts``.
+
+All owned ``did:nuts`` DID documents will be migrated to the new SQL storage.
+This migration includes all historic document updates as published upto a potential deactivation of the document.
+For DIDs with a document conflict this is different than the resolved version of the document, which contains a merge of all conflicting document updates.
+To prevent the state of the resolver and the SQL storage to be in conflict, all DID document conflicts must be resolved before upgrading to v6.
+See ``/status/diagnostics`` if you own any DIDs with a document conflict. If so, use ``/internal/vdr/v1/did/conflicted`` to find the DIDs with a conflict.
+
+.. note::
+
+    The document migration will run on every restart of the node, meaning that any updates made using the VDR V1 API will be migrated on the next restart.
+    However, any changes made via the V1 API wil NOT propagate to other DID documents under the same ``subject``, so you MUST set ``vdr.didmethods = ["nuts"]`` to use the V1 API.
+
+**Migration: add did:web to subjects**
+Requires ``vdr.didmethods`` to contain ``web`` and ``nuts`` (default).
+
+This migration adds a new ``did:web`` DID Document to owned subjects that do not already have one.
+All services from the ``did:nuts`` DID Document are copied to the new document.
+A new verification method is created for the document and added to all verification relationships except KeyAgreement.
+This means did:web cannot be used for encryption (yet).

docs/pages/integrating/version-incompatibilities.rst

@@ -11,17 +11,8 @@ There's also a config parameter that allows you to limit the DID methods in use.
 Not all combinations of API usage and DID methods are supported.
 There are basically two options.
 
-1. Keep using the VDR V1 API (for now) and set ``vdr.did_methods`` to ``["nuts"]``.
-2. Use the VDR V2 API and set ``vdr.did_methods`` to include other methods or leave blank for default setting.
+1. Keep using the VDR V1 API (for now) and set ``vdr.didmethods`` to ``["nuts"]``.
+2. Use the VDR V2 API and set ``vdr.didmethods`` to include other methods or leave blank for default setting.
 
 Do not use the VDR V1 and VDR V2 API at the same time. This will lead to unexpected behavior.
 Once you use the VDR V2 API, you cannot go back to the VDR V1 API. The VDR V1 API has also been marked as deprecated.
-
-Nodes running v6 with ``nuts`` configured as one of the ``vdr.did_methods`` will migrate all owned ``did:nuts`` DID documents to the new SQL storage.
-This migration includes all historic document updates as published upto a potential deactivation of the document.
-For DIDs with a document conflict this is different than the resolved version of the document, which contains a merge of all conflicting document updates.
-To prevent the state of the resolver and the SQL storage to be in conflict, all DID document conflicts must be resolved before upgrading to v6.
-See ``/status/diagnostics`` if you own any DIDs with a document conflict. If so, use ``/internal/vdr/v1/did/conflicted`` to find the DIDs with a conflict.
-
-The document migration will run on every restart of the node, meaning that any updates made using the VDR V1 API will be migrated on the next restart.
-When switching from the VDR V1 API to the V2 API, the node must be restarted first to migrate any recent changes.

docs/pages/release_notes.rst

@@ -64,6 +64,7 @@ You no longer manage changes to DIDs but to Subjects. Each subject has multiple
 You're free to choose an ID for a Subject. This feature enables forwards compatibility with new DID methods.
 DID methods can be enabled and disabled via the ``vdr.didmethods`` config parameter. (Default: ``['web','nuts']``).
 Existing ``did:nuts`` documents will be migrated to self-controlled at startup and the DID will be added as SubjectID.
+See :ref:`nuts-node-migrations` for more information.
 
 HTTP interface
 ==============
@@ -95,7 +96,10 @@ The following features have been deprecated:
   Starting v6, the preferred way to support other key storage backends is to directly implement it in the Nuts node itself.
   This also reduces the complexity of a Nuts node deployment (one service less to configure and deploy).
   Users are recommended to switch to the built-in client of their key storage backend.
-- VDR v1 API.
+- Auth v1 API, replaced by Auth v2
+- DIDMan v1 API, to be removed
+- Network v1 API, to be removed
+- VDR v1 API, replaced by VDR v2
 
 ************************
 Hazelnut update (v5.4.11)