diff --git a/docs/docs/dev_docs/updating.md b/docs/docs/dev_docs/updating.md
index 05c9b76de536..7d21478163c3 100644
--- a/docs/docs/dev_docs/updating.md
+++ b/docs/docs/dev_docs/updating.md
@@ -43,6 +43,7 @@ aztec-cli update . --contract src/contract1 --contract src/contract2
 
 The sandbox must be running for the update command to work.
 
+3. Refer [Migration Notes](../misc/migration_notes.md) on any breaking changes that might affect your dapp
 ---
 
 There are three components whose versions need to be kept compatible:
diff --git a/docs/docs/misc/migration_notes.md b/docs/docs/misc/migration_notes.md
new file mode 100644
index 000000000000..6c20da38de8a
--- /dev/null
+++ b/docs/docs/misc/migration_notes.md
@@ -0,0 +1,115 @@
+---
+title: Migration notes
+description: Read about migration notes from previous versions, which could solve problems while updating
+keywords: [sandbox, cli, aztec, notes, migration, updating, upgrading]
+---
+
+Aztec is in full-speed development. Literally every version breaks compatibility with the previous ones. This page attempts to target errors and difficulties you might encounter when upgrading, and how to resolve them.
+
+## 0.17.0
+
+### [js] New `@aztec/accounts` package
+
+Before: 
+
+```js
+import { getSchnorrAccount } from "@aztec/aztec.js" // previously you would get the default accounts from the `aztec.js` package:
+```
+
+Now, import them from the new package `@aztec/accounts`
+
+```js
+import { getSchnorrAccount } from "@aztec/accounts" 
+```
+
+### Typed Addresses
+Address fields in Aztec.nr now is of type `AztecAddress` as opposed to `Field`
+
+Before:
+```rust
+unconstrained fn compute_note_hash_and_nullifier(contract_address: Field, nonce: Field, storage_slot: Field, serialized_note: [Field; VALUE_NOTE_LEN]) -> [Field; 4] {
+        let note_header = NoteHeader::new(_address, nonce, storage_slot);
+        ...
+```
+
+Now:
+```rust
+unconstrained fn compute_note_hash_and_nullifier(
+        contract_address: AztecAddress,
+        nonce: Field,
+        storage_slot: Field,
+        serialized_note: [Field; VALUE_NOTE_LEN]
+    ) -> pub [Field; 4] {
+        let note_header = NoteHeader::new(contract_address, nonce, storage_slot);
+```
+
+Similarly, there are changes when using aztec.js to call functions.
+
+To parse a `AztecAddress` to BigInt, use `.inner`
+Before:
+```js
+const tokenBigInt = await bridge.methods.token().view()
+```
+
+Now:
+```js
+const tokenBigInt = (await bridge.methods.token().view()).inner
+```
+
+### [Aztec.nr] Add `protocol_types` to Nargo.toml
+```toml
+aztec = { git="https://github.com/AztecProtocol/aztec-packages/", tag="#include_aztec_version", directory="yarn-project/aztec-nr/aztec" }
+protocol_types = { git="https://github.com/AztecProtocol/aztec-packages/", tag="#include_aztec_version", directory="yarn-project/noir-protocol-circuits/src/crates/types"}
+```
+
+### [Aztec.nr] moving compute_address func to AztecAddress
+Before:
+```rust
+let calculated_address = compute_address(pub_key_x, pub_key_y, partial_address);
+```
+
+Now:
+```rust
+let calculated_address = AztecAddress::compute(pub_key_x, pub_key_y, partial_address);
+```
+
+### [Aztec.nr] moving `compute_selector` to FunctionSelector
+Before:
+```rust
+let selector = compute_selector("_initialize((Field))");
+```
+
+Now:
+```rust
+let selector = FunctionSelector::from_signature("_initialize((Field))");
+```
+
+### [js] Importing contracts in JS
+
+Contracts are now imported from a file with the type's name.
+
+Before:
+```js
+import { TokenContract } from "@aztec/noir-contracts/types";
+```
+
+Now:
+```js
+import { TokenContract } from "@aztec/noir-contracts/Token";
+```
+
+### [Aztec.nr] Aztec example contracts location change in Nargo.toml
+
+Aztec contracts are now moved outside of the `src` folder, so you need to update your imports.
+
+Before:
+```rust
+easy_private_token_contract = {git = "https://github.com/AztecProtocol/aztec-packages/", tag ="v0.16.9", directory = "yarn-project/noir-contracts/src/contracts/easy_private_token_contract"}
+```
+
+Now, just remove the `src` folder,:
+
+```rust
+easy_private_token_contract = {git = "https://github.com/AztecProtocol/aztec-packages/", tag ="v0.17.0", directory = "yarn-project/noir-contracts/contracts/easy_private_token_contract"}
+```
+
diff --git a/docs/sidebars.js b/docs/sidebars.js
index 4eb6dbdcac77..8d9748c6b545 100644
--- a/docs/sidebars.js
+++ b/docs/sidebars.js
@@ -81,9 +81,7 @@ const sidebars = {
             type: "doc",
             id: "concepts/foundation/state_model/main",
           },
-          items: [
-            "concepts/foundation/state_model/storage_slots"
-          ]
+          items: ["concepts/foundation/state_model/storage_slots"],
         },
         {
           label: "Accounts",
@@ -113,8 +111,8 @@ const sidebars = {
                 id: "concepts/foundation/communication/public_private_calls/main",
               },
               items: [
-                "concepts/foundation/communication/public_private_calls/slow_updates_tree"
-              ]
+                "concepts/foundation/communication/public_private_calls/slow_updates_tree",
+              ],
             },
             "concepts/foundation/communication/cross_chain_calls",
           ],
@@ -324,9 +322,7 @@ const sidebars = {
                 type: "doc",
                 id: "dev_docs/contracts/syntax/storage/main",
               },
-              items: [
-                "dev_docs/contracts/syntax/storage/storage_slots",
-              ]
+              items: ["dev_docs/contracts/syntax/storage/storage_slots"],
             },
             "dev_docs/contracts/syntax/events",
             "dev_docs/contracts/syntax/functions",
@@ -361,10 +357,10 @@ const sidebars = {
             {
               label: "Common Patterns",
               type: "category",
-                    link: {
-                      type: "doc",
-                      id: "dev_docs/contracts/resources/common_patterns/main",
-                    },
+              link: {
+                type: "doc",
+                id: "dev_docs/contracts/resources/common_patterns/main",
+              },
               items: [
                 "dev_docs/contracts/resources/common_patterns/authwit",
                 //         "dev_docs/contracts/resources/common_patterns/sending_tokens_to_user",
@@ -478,7 +474,7 @@ const sidebars = {
       value: "Miscellaneous",
       defaultStyle: true,
     },
-
+    "misc/migration_notes",
     "misc/glossary",
 
     {