From cdbff371a411490377a52d46373bd1373cb32752 Mon Sep 17 00:00:00 2001
From: bgallois <benjamin@gallois.cc>
Date: Fri, 22 Mar 2024 17:24:05 +0100
Subject: [PATCH] upgrade documentation
---
docs/dev/upgrade-substrate.md | 60 +++++++++++++++++++++--------------
1 file changed, 36 insertions(+), 24 deletions(-)
diff --git a/docs/dev/upgrade-substrate.md b/docs/dev/upgrade-substrate.md
index 2345be020..c151bd603 100644
--- a/docs/dev/upgrade-substrate.md
+++ b/docs/dev/upgrade-substrate.md
@@ -1,31 +1,43 @@
-# Upgrade Substrate
+# Polkadot Upgrade Guide
-We need to keep up to date with Substrate. Here is an empirical guide.
+ParityTech frequently releases upgrades of the polkadot-sdk. For each upgrade, Duniter should be upgraded following the instructions below. These instructions are based on upgrading from version 1.8.0 to 1.9.0.
-Let's say for the example that we want to upgrade from `v0.9.26` to `v0.9.32`.
+## 1. Upgrade the duniter-polkadot-sdk
-## Upgrade Substrate fork
-1. Checkout the latest Substrate Polkadot branch `polkadot-v0.9.xy` in [our Substrate](https://github.com/duniter/substrate/)
-2. Create a new branch `duniter-substrate-v0.9.xy`
-3. Cherry-pick `3ad5e1a1fdac5398d4911272a34e1f16c1bdd8f0`, `87ef489034ca2b15c4f30da387e06b1f6716d9a2` and `c36ab4f32454318a47777b24b6533c44121fc10b`
-4. Run `cargo check` to check the cherry-picking
+* Clone the repository: `git clone git@github.com:duniter/duniter-polkadot-sdk.git`
+* Set the upstream repository: `git remote add upstream git@github.com:paritytech/polkadot-sdk.git`
+* Fetch the latest released version: `git fetch --tag polkadot-v1.9.0`
+* Create a new branch: `git checkout -b duniter-polkadot-v1.9.0`
+* Rebase the branch, keeping only specific commits: "fix treasury benchmarks when no SpendOrigin", "allow manual seal to produce non-empty blocks with BABE", "add custom pallet-balance GenesisConfig", and "remove pallet-balances upgrade_account extrinsic".
+* Push the new branch: `git push`
-## Upgrade Subxt fork
+## 2. Upgrade duniter subxt
-1. Checkout the currently used branch in [our Subxt fork](https://github.com/duniter/subxt), e.g. `duniter-substrate-v0.9.26`
-2. Create a new branch `duniter-substrate-v0.9.32`
-3. Fetch the [upstream repository](https://github.com/paritytech/subxt)
-4. Rebase on an upstream stable branch matching the wanted version
+* Clone the repository: `git clone git@github.com:duniter/subxt.git`
+* Set the upstream repository: `git remote add upstream git@github.com:paritytech/subxt.git`
+* If a new version compatible with the polkadot-sdk version used in duniter is available, upgrade Subxt using the same method as duniter-polkadot-sdk.
+* In the `Cargo.toml` file of duniter subxt, change the GitHub path pointing to the paritytech polkadot-sdk, or old duniter-polkadot-sdk to the new duniter-polkadot-sdk.
+* Run `cargo upgrade` and push the branch.
-## Upgrade Duniter
+## 3. Upgrade repository
-1. Replace `duniter-substrate-v0.9.26` with `duniter-substrate-v0.9.32` in `Cargo.toml`
-2. Update the `rust-toolchain` file according to [Polkadot release notes](https://github.com/paritytech/polkadot/releases)
- * Tip: To save storage space on your machine, do `rm target -r` after changing the rust toolchain version and before re-building the project with the new version.
-3. While needed, iterate `cargo check`, `cargo update` and upgrading dependencies to match substrate's dependencies
-4. Fix errors in Duniter code
- * You may need to check how Polkadot is doing by searching in [their repo](https://github.com/paritytech/polkadot). Luckily, the project structure and Substrate patterns are close enough to ours.
- * Some errors may happen due to two semver-incompatible versions of a same crate being used. To check this, use `cargo tree -i <crate>`. Update the dependency accordingly, then do `cargo update`.
-5. As always, don't forget to `clippy` once you're done with the errors.
-6. Test benchmarking:
- `cargo run --features runtime-benchmarks -- benchmark overhead --chain=dev --execution=wasm --wasm-execution=interpreted-i-know-what-i-do --weight-path=. --warmup=10 --repeat=100`
\ No newline at end of file
+* In the `Cargo.toml` file of Duniter, change the version number from 1.8.0 to 1.9.0 for all polkadot-sdk dependencies. Also, change the version for Subxt. `find . -type f -name "Cargo.toml" -exec sed -i'' -e 's/polkadot-v1.8.0\/polkadot-v1.9.0/g' {} +`.
+* Upgrade the version number of all crateio dependencies to ensure compatibility with those used in the polkadot-sdk, see the node template at: [Node Template](https://github.com/paritytech/polkadot-sdk/blob/master/templates/solochain/node/Cargo.toml) (choose the correct branch/tag).
+
+At this point, two cases may arise:
+
+1. If the upgrade only adds some types and minor changes, add the types in the pallet configuration, replace the offending `WeightInfo`, and delete the corresponding weights files until they can be regenerated.
+
+2. If there are many breaking changes, it is recommended to break down the process:
+
+ * Start by correcting errors on individual pallets using `cargo check -p my_pallet` to identify and rectify any errors. Then, test using `cargo test -p my_pallet` and benchmark using `cargo test -p my_pallet --feature runtime-benchmark`.
+ * After correcting all pallets, fix the runtimes using the same approach: check for trait declarations added or removed in each pallet configuration, and use `cargo check -p runtime`, `cargo test -p runtime`, and `cargo test -p runtime --feature runtime-benchmark`.
+ * Repeat this process with the node part, the distance-oracle, all the tests, xtask, and the client.
+ * Conclude the process by executing all benchmarks using the command `scripts/run_all_benchmarks.sh`.
+
+## 4. Troubleshooting
+
+As Duniter may sometimes be the only chain implementing advanced features, such as manual sealing, not many references can be found. However, the following projects may be useful:
+
+* Node template for general up-to-date implementation: [Node Template](https://github.com/paritytech/polkadot-sdk/tree/master/templates)
+* Acala: [Acala](https://github.com/AcalaNetwork/Acala), which also uses manual sealing add a similar node implementation.
--
GitLab