DOCSP-19335: migration guide for community driver users (#210)

* DOCSP-19335: migration guide for community driver users

Author: Chris Cho

config/redirects

@@ -18,7 +18,7 @@ raw: kafka-connector/ -> ${base}/current/
 [*-master]: kafka-connector/${version}/kafka-sink-postprocessors/ -> ${base}/${version}/sink-connector/fundamentals/post-processors/
 [*-master]: kafka-connector/${version}/fundamentals/post-processors/ -> ${base}/${version}/sink-connector/fundamentals/post-processors/
 [*-master]: kafka-connector/${version}/kafka-sink-time-series-example/ -> ${base}/${version}/tutorials/migrate-time-series/
-[*-master]: kafka-connector/${version}/kafka-connect-migration/ -> ${base}/${version}/
+[*-master]: kafka-connector/${version}/kafka-connect-migration/ -> ${base}/${version}/migrate-from-kafka-connect-mongodb/
 
 [*-v1.5]: kafka-connector/${version}/tutorials/migrate-time-series/ -> ${base}/${version}/
 [*-v1.5]: kafka-connector/${version}/sink-connector/configuration-properties/time-series/ -> ${base}/${version}/

source/index.txt

@@ -19,6 +19,7 @@ MongoDB Kafka Connector
    Sink Connector </sink-connector>
    Source Connector </source-connector>
    Security and Authentication </security-and-authentication>
+   Migrate from the Community Connector <migrate-from-kafka-connect-mongodb>
    Troubleshooting </troubleshooting>
    How to Contribute </contribute>
    Issues & Help </issues-and-help>
@@ -43,6 +44,7 @@ sections:
 - :doc:`Sink Connector </sink-connector>`
 - :doc:`Source Connector </source-connector>`
 - :doc:`Security and Authentication </security-and-authentication>`
+  :doc:`Migrate from the Community Connector </migrate-from-kafka-connect-mongodb>`
 - :doc:`Troubleshooting </troubleshooting>`
 - :doc:`How to Contribute </contribute>`
 - :doc:`Issues & Help </issues-and-help>`

source/migrate-from-kafka-connect-mongodb.txt

@@ -0,0 +1,80 @@
+.. _migrate-from-kafka-connect-mongodb:
+
+==================================
+Migrate from Kafka Connect MongoDB
+==================================
+
+.. default-domain:: mongodb
+
+Use this guide to migrate your Kafka deployments from the community-created
+:github:`Kafka Connect MongoDB <hpgrahsl/kafka-connect-mongodb>` sink connector
+to the :github:`official MongoDB Kafka connector <mongodb/mongo-kafka>`.
+
+The following sections list the changes you must make to your Kafka
+Connect sink connector configuration settings and custom classes to transition
+to the MongoDB Kafka connector.
+
+Update Configuration Settings
+-----------------------------
+
+Make the following changes to the configuration settings of your Kafka Connect
+deployment before using them with your MongoDB Kafka connector deployment:
+
+- Replace values that include the package ``at.grahsl.kafka.connect.mongodb``
+  with the package ``com.mongodb.kafka.connect``.
+
+- Replace your ``connector.class`` setting with the MongoDB Kafka sink
+  connector class.
+
+  .. code-block:: properties
+
+     connector.class=com.mongodb.kafka.connect.MongoSinkConnector
+
+- Remove the ``mongodb.`` prefix from your Kafka Connect property names.
+  For example, change ``mongodb.connection.uri`` to ``connection.uri``.
+
+- Remove the ``document.id.strategies`` setting if it exists. If the value of
+  this setting reference custom strategies, move them to the
+  ``document.id.strategy`` setting. Read the :ref:`<custom-class-changes>`
+  section to discover what changes you must make to your custom classes.
+
+- Replace any property names you use to specify per-topic or collection
+  overrides that contain the ``mongodb.collection`` prefix with the equivalent
+  key in
+  :ref:`sink connector Kafka topic configuration topic properties <sink-configuration-topic-properties>`.
+
+.. _custom-class-changes:
+
+Update Custom Classes
+---------------------
+
+If you use any custom classes in your Kafka Connect sink connector deployment,
+make the following changes to them before adding them to your MongoDB Kafka
+connector deployment:
+
+- Replace imports that include ``at.grahsl.kafka.connect.mongodb`` with
+  ``com.mongodb.kafka.connect``.
+
+- Replace references to the ``MongoDbSinkConnector`` class with the
+  ``MongoSinkConnector`` class.
+
+- Update custom sink connector strategy classes to implement the
+  ``com.mongodb.kafka.connect.sink.processor.id.strategy.IdStrategy``
+  interface.
+
+- Update references to the ``MongoDbSinkConnectorConfig`` class. In the
+  MongoDB Kafka connector, the logic from that class is split into the
+  following classes:
+
+  - :github:`MongoSinkConfig <mongodb/mongo-kafka/blob/master/src/main/java/com/mongodb/kafka/connect/sink/MongoSinkConfig.java>`
+  - :github:`MongoSinkTopicConfig <mongodb/mongo-kafka/blob/master/src/main/java/com/mongodb/kafka/connect/sink/MongoSinkTopicConfig.java>`
+
+
+Update Post Processor Subclasses
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+If you have classes that subclass a post processor in your Kafka Connect
+connector deployment, update methods that override ones in the Kafka Connect
+``PostProcessor`` class to match the method signatures of the MongoDB Kafka
+connector :github:`PostProcessor class <mongodb/mongo-kafka/blob/master/src/main/java/com/mongodb/kafka/connect/sink/processor/PostProcessor.java>`.
+

source/sink-connector/configuration-properties/kafka-topic.txt

@@ -1,3 +1,5 @@
+.. _sink-configuration-topic-properties:
+
 ======================
 Kafka Topic Properties
 ======================