diff --git a/CHANGELOG.md b/CHANGELOG.md
index 89be12b..8be40f3 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,8 +1,9 @@
 # sourced v4
-- Typescript rewrite - thanks to work on this at https://github.com/PDMLab/sourced-ts 
+- Typescript rewrite - thanks to work on this at https://github.com/PDMLab/sourced-ts by @alexander.zeitler and @stephanknull, pulled in by @patrickleet
+- BREAKING CHANGE: now publishes ESM and CJS modules at /dist/esm and /dist/cjs
 
 # sourced v3
-- Browser support by using `eventemitter3.EventEmitter` instead of Node `events.EventEmitter`
+- Browser support by using `eventemitter3.EventEmitter` instead of Node `events.EventEmitter` by @patrickleet
 - BREAKING CHANGE: `Entity` is now `EntityProxy`. `SourcedEntity` is now `Entity`
 
 # sourced v2
diff --git a/README.md b/README.md
index 452e950..8a12f35 100644
--- a/README.md
+++ b/README.md
@@ -403,3 +403,22 @@ const Entity = require('sourced').EntityProxy
 ```
 
 See examples directory for an examply of using the `EntityProxy` - run it with `npm ci && npm run build && node examples/auth/example.js`
+
+# Upgrading 
+
+## sourced v4
+- Typescript rewrite - thanks to work on this at https://github.com/PDMLab/sourced-ts by @alexander.zeitler and @stephanknull, pulled in by @patrickleet
+- BREAKING CHANGE: now publishes ESM and CJS modules at /dist/esm and /dist/cjs
+
+## sourced v3
+- Browser support by using `eventemitter3.EventEmitter` instead of Node `events.EventEmitter` by @patrickleet
+- BREAKING CHANGE: `Entity` is now `EntityProxy`. `SourcedEntity` is now `Entity`
+
+## sourced v2
+- updated to ES6 syntax by @patrickleet
+- `SourcedEntity` an ES6 implementation of `Entity` added.
+- `Entity` is now just a proxy to the new `SourcedEntity` ES6 class. 
+- Deprecation notice: `SourcedEntity` will become `Entity` in the next major version, and `Entity`, which is now a proxy, left for backwards compatibility 
+
+## sourced v1
+- original lib by @mateodelnorte - battle tested in financial systems that tranact billions of dollars.
\ No newline at end of file