From 472fddad723773f650bb9a1d24470cbf80e61c17 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Jos=C3=A9=20Pedro=20Sousa?= <jose@aztecprotocol.com>
Date: Mon, 8 Jan 2024 15:37:37 +0000
Subject: [PATCH] chore(docs): starting a migration notes section (#3853)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

At the request of many families (I guess this portuguese expression
isn't really translatable)... we're replicating the "migration notes"
section in Noir docs to help devs keep track of breaking changes

---------

Co-authored-by: José Pedro Sousa <github@zepedro.me>
Co-authored-by: Josh Crites <jc@joshcrites.com>
Co-authored-by: Rahul Kothari <rahul.kothari.201@gmail.com>
---
 docs/docs/dev_docs/updating.md    |   1 +
 docs/docs/misc/migration_notes.md | 115 ++++++++++++++++++++++++++++++
 docs/sidebars.js                  |   2 +-
 3 files changed, 117 insertions(+), 1 deletion(-)
 create mode 100644 docs/docs/misc/migration_notes.md

diff --git a/docs/docs/dev_docs/updating.md b/docs/docs/dev_docs/updating.md
index 05c9b76de53..7d21478163c 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 00000000000..6c20da38de8
--- /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 76794b94616..b65035ba968 100644
--- a/docs/sidebars.js
+++ b/docs/sidebars.js
@@ -479,7 +479,7 @@ const sidebars = {
       value: "Miscellaneous",
       defaultStyle: true,
     },
-
+    "misc/migration_notes",
     "misc/glossary",
 
     {