chore: add a transition guide. fixes cloudevents#360

Signed-off-by: Lucas Holmquist <lholmqui@redhat.com>

Author: lholmquist

API_TRANSITION_GUIDE.md

@@ -0,0 +1,62 @@
+## Deprecated API Transition Guide
+
+When API's are deprecated, the following guide will show how to transition from removed API's to the new ones
+
+
+### Upgrading From 3.x to 4.0
+
+In the 3.2.0 release, a few API's were set to be deprecated in the 4.0 release.  With the release of 4.0.0,  those API's have been removed.
+
+#### Receiever
+
+The `Receiver` class has been removed.
+
+`Receiver.accept` should be transitioned to `HTTP.toEvent`
+
+#### Emitter
+
+The `Emitter` class has been removed.
+
+`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 }));
+```

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) |