From 79296a8e63b43325a51d7e6c9ba29d04066dee17 Mon Sep 17 00:00:00 2001
From: Lucas Holmquist <lholmqui@redhat.com>
Date: Mon, 7 Dec 2020 11:21:30 -0500
Subject: [PATCH] chore: add a transition guide.  fixes #360 (#363)

Signed-off-by: Lucas Holmquist <lholmqui@redhat.com>
---
 API_TRANSITION_GUIDE.md | 102 ++++++++++++++++++++++++++++++++++++++++
 README.md               |   5 ++
 2 files changed, 107 insertions(+)
 create mode 100644 API_TRANSITION_GUIDE.md

diff --git a/API_TRANSITION_GUIDE.md b/API_TRANSITION_GUIDE.md
new file mode 100644
index 0000000..4370a73
--- /dev/null
+++ b/API_TRANSITION_GUIDE.md
@@ -0,0 +1,102 @@
+## Deprecated API Transition Guide
+
+When APIs are deprecated, the following guide will show how to transition from removed APIs to the new ones
+
+
+### Upgrading From 3.x to 4.0
+
+In the 3.2.0 release, a few APIs were set to be deprecated in the 4.0 release.  With the release of 4.0.0,  those APIs have been removed.
+
+#### Receiever
+
+The `Receiver` class has been removed.
+
+`Receiver.accept` should be transitioned to `HTTP.toEvent`
+
+Here is an example of what a `HTTP.toEvent` might look like using Express.js
+
+```js
+const app = require("express")();
+const { HTTP } = require("cloudevents");
+
+app.post("/", (req, res) => {
+  // body and headers come from an incoming HTTP request, e.g. express.js
+  const receivedEvent = HTTP.toEvent({ headers: req.headers, body: req.body });
+  console.log(receivedEvent);
+});
+```
+
+#### Emitter
+
+`Emit.send` should be transitioned to `HTTP.binary` for binary events and `HTTP.structured` for structured events
+
+`Emit.send` would use axios to emit the events.  Since this now longer available, you are free to choose your own transport protocol.
+
+So for axios,  it might look something like this:
+
+```js
+const axios = require('axios').default;
+const { HTTP } = require("cloudevents");
+
+
+const ce = new CloudEvent({ type, source, data })
+const message = HTTP.binary(ce); // Or HTTP.structured(ce)
+
+axios({
+  method: 'post',
+  url: '...',
+  data: message.body,
+  headers: message.headers,
+});
+```
+
+You may also use the `emitterFor()` function as a convenience.
+
+```js
+const axios = require('axios').default;
+const { emitterFor, Mode } = require("cloudevents");
+
+function sendWithAxios(message) {
+  // Do what you need with the message headers
+  // and body in this function, then send the
+  // event
+  axios({
+    method: 'post',
+    url: '...',
+    data: message.body,
+    headers: message.headers,
+  });
+}
+
+const emit = emitterFor(sendWithAxios, { mode: Mode.BINARY });
+emit(new CloudEvent({ type, source, data }));
+```
+
+You may also use the `Emitter` singleton
+
+```js
+const axios = require("axios").default;
+const { emitterFor, Mode, CloudEvent, Emitter } = require("cloudevents");
+
+function sendWithAxios(message) {
+  // Do what you need with the message headers
+  // and body in this function, then send the
+  // event
+  axios({
+    method: "post",
+    url: "...",
+    data: message.body,
+    headers: message.headers,
+  });
+}
+
+const emit = emitterFor(sendWithAxios, { mode: Mode.BINARY });
+// Set the emit
+Emitter.on("cloudevent", emit);
+
+...
+// In any part of the code will send the event
+new CloudEvent({ type, source, data }).emit();
+
+// You can also have several listener to send the event to several endpoint
+```
diff --git a/README.md b/README.md
index fb850fa..f274a40 100644
--- a/README.md
+++ b/README.md
@@ -138,6 +138,11 @@ There are a few trivial example applications in
 [the examples folder](https://github.com/cloudevents/sdk-javascript/tree/main/examples).
 There you will find Express.js, TypeScript and Websocket examples.
 
+
+### API Transition Guide
+
+[Guide Link](./API_TRANSITION_GUIDE.md)
+
 ## Supported specification features
 
 | Core Specification | [v0.3](https://github.com/cloudevents/spec/blob/v0.3/spec.md) | [v1.0](https://github.com/cloudevents/spec/blob/v1.0/spec.md) |