update readme, changes, version (#137)

* chore: prepare for 0.200.0 release

* docs: update README and CHANGES

- readme: update build badge
- readme: remove pre-release section
- changes: reword readme change
- changes: clarify moves and renames with instructions for changing
  properties file
- changes: add entry for record key format
- changes: add entry for dlq/errors
- changes: add entry for batch semantics
- changes: re-order with most important breaking changes first
- changes: whitespace, wrap at 120 chars

* docs: fix copy/paste

* docs: implicitly sort by date and include prereleases in badge

* docs: PR feedback

* docs: PR feedback

* docs: suggested installation changes for zip distribution

* Apply suggestions from code review

Co-authored-by: Rich Ellis <[email protected]>

Co-authored-by: Thomas Blench <[email protected]>
Co-authored-by: Rich Ellis <[email protected]>

Author: tomblench

CHANGES.md

@@ -1,17 +1,33 @@
-# UNRELEASED
-- [FIXED] README to align with the 2.8.0 Kafka version.
-- [BREAKING CHANGE] Refactor package names
-- [BREAKING CHANGE] Source and sink connector moves and renames
-- [BREAKING CHANGE] Source connector flatten, schema generation and omit design documents options have been replaced by message transforms. See README for details.
-- [BREAKING CHANGE] Source connector now emits `java.util.Map` (not `String`) record values by default. See README for details.
-- [BREAKING CHANGE] Source connector now emits tombstone events for deleted documents. See [single message transforms](README.md#single-message-transforms) section in README for details.
+# 0.200.0 (2022-11-01)
+
+- [FIXED] README and documentation have been extensively rewritten.
+- [BREAKING CHANGE] Rename source connector. Properties files should be updated to
+  use `connector.class=com.ibm.cloud.cloudant.kafka.SourceChangesConnector`.
+- [BREAKING CHANGE] Rename sink connector. Properties files should be updated to
+  use `connector.class=com.ibm.cloud.cloudant.kafka.SinkConnector`.
+- [BREAKING CHANGE] Configuration parameters have changed for url, database, authentication, and last change sequence.
+  See README for details.
+- [BREAKING CHANGE] Source connector flatten, schema generation and omit design documents options have been replaced by
+  message transforms. See README for details.
+- [BREAKING CHANGE] Source connector now emits `java.util.Map` (not `String`) event values by default. See README for
+  details.
+- [BREAKING CHANGE] Source connector now emits `org.apache.kafka.connect.data.Struct` (not `String`) event keys. See
+  README for details.
+- [BREAKING CHANGE] Source connector now emits tombstone events for deleted documents.
+  See [single message transforms](README.md#single-message-transforms) section in README for details.
+- [BREAKING CHANGE] Converter support for sink connector has changed. See README for details.
+- [BREAKING CHANGE] Preserve `_rev` field message values in sink connector.
+  See [sink connector config](README.md#converter-configuration-sink-connector) section in README for more details.
+- [BREAKING CHANGE] Semantics of `batch.size` configuration parameter changed: for sink connector this value no longer
+  affects when `flush()` is called.
+- [BREAKING CHANGE] Sink connector will correctly honour `errors.tolerance`, `errors.log.enable`,
+  and `errors.deadletterqueue.topic.name` configuration parameters.
+  See [the sample sink properties file](docs/connect-cloudant-sink-example.properties) for a recommended example of how
+  to configure these to continue processing when non-fatal errors occur.
+- [BREAKING CHANGE] Renamed from `kafka-connect-cloudant` to `cloudant-kafka-connector` and packaged as zipped directory instead of uber jar. See README for installation details.
 - [BREAKING CHANGE] Publish releases to https://github.com/IBM/cloudant-kafka-connector/releases.
-- [BREAKING CHANGE] Rename package from `com.ibm.cloudant.kafka` to `com.ibm.cloud.cloudant.kafka`. Existing `connector.class` property values must be updated to use the new package.
-- [BREAKING CHANGE] Rename module from `kafka-connect-cloudant` to `cloudant-kafka-connector`.
-- [BREAKING CHANGE] Converter support for sink connector has changed. See README.md for details.
-- [BREAKING CHANGE] Configuration parameters have changed for url, database, authentication, and last change sequence. See README.md for details.
-- [BREAKING CHANGE] Preserve `_rev` field message values in sink connector.  See [sink connector config](README.md#converter-configuration-sink-connector) section in README for more details.
-- [UPGRADED] Connector now supports all authentication types via the `cloudant.auth.type` configuration parameter. When using an authentication type of "iam", the API key is configured via the `cloudant.apikey` configuration parameter.
+- [UPGRADED] Connector now supports all authentication types via the `cloudant.auth.type` configuration parameter. When
+  using an authentication type of "iam", the API key is configured via the `cloudant.apikey` configuration parameter.
 - [UPGRADED] Upgraded Gradle distribution from 4.5.1 to 7.4
 - [UPGRADED] Upgraded Kafka Connect API to 3.2.1.
 - [UPGRADED] Refactored to use the new `cloudant-java-sdk` library.

README.md

@@ -1,6 +1,6 @@
 # Cloudant Kafka Connector
 
-[![Maven Central](https://img.shields.io/maven-central/v/com.cloudant/kafka-connect-cloudant.svg)](http://search.maven.org/#search|ga|1|g:"com.cloudant"%20AND%20a:"kafka-connect-cloudant")
+[![Release](https://img.shields.io/github/v/release/IBM/cloudant-kafka-connector?include_prereleases)](https://github.com/IBM/cloudant-kafka-connector/releases/latest)
 
 This project includes [Apache Kafka](https://kafka.apache.org/) [Connect](https://kafka.apache.org/documentation.html#connect) source and sink connectors for IBM Cloudant.
 
@@ -10,14 +10,6 @@ These connectors can stream events:
 
 _Note:_ the connectors are also compatible with Apache CouchDB.
 
-## Pre-release
-
-**Note**: this README file is for a pre-release version of the
-connector. This means it refers to configuration options and features
-which are different to the currently released version. For information
-about the currently released version, please see the [README
-here](https://github.com/IBM/cloudant-kafka-connector/blob/0.100.2-kafka-1.0.0/README.md).
-
 ## Release Status
 
 Experimental
@@ -28,10 +20,19 @@ Experimental
 
 ### Quick Start
 
-1. Download the jar from the [releases page](https://github.com/IBM/cloudant-kafka-connector/releases). The jar file contains the plugin and the non-Kafka dependencies needed to run.
-2. Copy the jar to the `libs` directory _or_ the
-[configured `plugin.path`](https://kafka.apache.org/documentation.html#connectconfigs_plugin.path) of your Kafka installation.
-3. Edit the [source](docs/connect-cloudant-changes-source-example.properties) or [sink](docs/connect-cloudant-sink-example.properties) example properties files and save this to the `config` directory of your Kafka installation.
+1. Download the zip from the [releases page](https://github.com/IBM/cloudant-kafka-connector/releases). The zip file
+   contains the plugin jar and the non-Kafka dependencies needed to run.
+2. Configure the [Kafka connect plugin path](https://kafka.apache.org/documentation.html#connectconfigs_plugin.path) for
+   your Kafka distribution, for example: `plugin.path=/kafka/connect`.
+   - This will be configured in either `connect-standalone.properties` or `connect-distributed.properties` in
+     the `config` directory of your Kafka installation.
+   - If you're not sure which to use, edit `connect-standalone.properties` and follow the standalone execution
+     instructions below.
+2. Unzip and move to the plugin path configured earlier, for example:
+   `unzip cloudant-kafka-connector-x.y.z.zip; mv cloudant-kafka-connector-x.y.z /kafka/connect`.
+3. Edit the [source](docs/connect-cloudant-changes-source-example.properties)
+   or [sink](docs/connect-cloudant-sink-example.properties) example properties files and save this to the `config`
+   directory of your Kafka installation.
 4. Start Kafka.
 5. Start the connector (see below).
 
@@ -116,7 +117,7 @@ For the source connector:
 * Values are produced as a (schemaless) `java.util.Map<String, Object>`.
 * These types are compatible with the default `org.apache.kafka.connect.json.JsonConverter` and should be compatible with any other converter that can accept a `Struct` or `Map`.
 * The `schemas.enable` may be safely used with a `key.converter` if desired.
-* The source connector does not generate schemas for the record values by default. To use `schemas.enable` with the `value.converter` consider using a schema registry or the [`MapToStruct` SMT](docs/smt-reference.md#map-to-struct-conversion).
+* The source connector does not generate schemas for the event values by default. To use `schemas.enable` with the `value.converter` consider using a schema registry or the [`MapToStruct` SMT](docs/smt-reference.md#map-to-struct-conversion).
 
 #### Converter Configuration: sink connector
 

VERSION

@@ -1 +1 @@
-0.200.0-SNAPSHOT
+0.200.0