From ff2911152234f3cd2838087afe5540d615a3b6bf Mon Sep 17 00:00:00 2001
From: Glynn Bird <glynnbird@apache.org>
Date: Mon, 4 Nov 2024 11:47:38 +0000
Subject: [PATCH] added migration guide

---
 README.md                     |  1 +
 migration_guide_v10_to_v11.md | 45 +++++++++++++++++++++++++++++++++++
 2 files changed, 46 insertions(+)
 create mode 100644 migration_guide_v10_to_v11.md

diff --git a/README.md b/README.md
index 076bf76..0799119 100644
--- a/README.md
+++ b/README.md
@@ -5,6 +5,7 @@
 Offical [Apache CouchDB](https://couchdb.apache.org/) library for [Node.js](https://nodejs.org/).
 
 > Note: Nano >=11.0.0 is a **breaking change for Node.js versions 16 and older**. Nano 11 uses Node.js's built-in "fetch" HTTP client but this is only available in Node.js versions 18 or later. If you are using Node 16 or older then continue using Nano 10.
+> See our [migration guide](migration_guide_v10_to_v11.md) for moving from Nano 10 to Nano 11.
 
 Features:
 
diff --git a/migration_guide_v10_to_v11.md b/migration_guide_v10_to_v11.md
new file mode 100644
index 0000000..2883a69
--- /dev/null
+++ b/migration_guide_v10_to_v11.md
@@ -0,0 +1,45 @@
+# Migrating from Nano 10 to Nano 11
+
+Nano 10 uses the Axios library as an HTTP/HTTPS client. Keeping up with changes to Axios and its dependencies made maintaining this library a chore, so as of Nano 11 we use Node.js's built-in _fetch_ API as our HTTP client. This makes Nano a _zero dependency_ library which makes for faster installs, easier maintenance and slightly better performance.
+
+There are some things to bear in mind if you are switching from Nano 10 to Nano 11, so please consider the following advice carefully before you do.
+
+## Node.js versions
+
+> ** Nano 11 is a breaking change for users of Node.s 16 or earlier **
+
+Nano 11 is only compatible with Node.js versions 18 and older, because it is only these Node versions that have the [fetch](https://nodejs.org/dist/latest-v18.x/docs/api/globals.html#fetch) HTTP client baked in. See [Node.js's Long-term Support page](https://nodejs.org/en/about/previous-releases) to see which are the currently supported and maintained versions. In short:
+
+- If you are using Node.js 18 or newer, use Nano 11.
+- If you need to use Node.js 16 or older, use Nano 10.
+
+Nano 10 may continue to receive some security fixes for a time, but Nano 11 represents the future of this project and at some point, support for Nano 10 will cease.
+
+## Agent options
+
+None of Nano's API has changed _except_ when a user is supplying non-default connection handling parameters. Gone is `requestDefaults` which dates back to the "request" days and instead an optional `agentOptions` can be provided which is documented in the README and in TypeScript.
+
+```js
+const agentOptions = {
+  bodyTimeout: 30000,
+  headersTimeout: 30000,
+  keepAliveMaxTimeout: 600000,
+  keepAliveTimeout: 30000,
+  keepAliveTimeoutThreshold: 1000,
+  maxHeaderSize: 16384,
+  maxResponseSize: -1,
+  pipelining: 6,
+  connect: { 
+    timeout: 10000
+  },
+  strictContentLength: true,
+  connections: null,
+  maxRedirections: 0
+}
+const undici = require('undici')
+const undiciOptions = new undici.Agent(agentOptions)
+const nano = Nano({ url: 'http://127.0.0.1:5984', undiciOptions })
+```
+
+> Note: to supply a custom agent, you will need the [undici](https://www.npmjs.com/package/undici) module as a dependency in your own project. Undici is the library that powers Node.js's _fetch_ API but its "Agent" is not programmatically accessible unless undici is imported separately.
+