diff --git a/README.md b/README.md
index 9a3c3fa6..2eebd78c 100644
--- a/README.md
+++ b/README.md
@@ -1,8 +1,24 @@
 # go-oidc
 
-[![GoDoc](https://godoc.org/github.com/coreos/go-oidc?status.svg)](https://pkg.go.dev/github.com/coreos/go-oidc/v3/oidc)
+[![Go Reference](https://pkg.go.dev/badge/github.com/coreos/go-oidc/v3/oidc.svg)](https://pkg.go.dev/github.com/coreos/go-oidc/v3/oidc)
 ![github.com/coreos/go-oidc/v3](https://github.com/coreos/go-oidc/workflows/test/badge.svg?branch=v3)
 
+## Updates from v2 to v3
+
+There were two breaking changes made to the v3 branch. The import path has changed from:
+
+```
+github.com/coreos/go-oidc
+```
+
+to:
+
+```
+github.com/coreos/go-oidc/v3/oidc
+```
+
+And the return type of `NewRemoteKeySet()` is now `*RemoteKeySet` instead of an interface ([#262](https://github.com/coreos/go-oidc/pull/262)).
+
 ## OpenID Connect support for Go
 
 This package enables OpenID Connect support for the [golang.org/x/oauth2](https://godoc.org/golang.org/x/oauth2) package.