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
* Clone the repository: `git clone git@github.com:duniter/duniter-polkadot-sdk.git`
1. Checkout the latest Substrate Polkadot branch `polkadot-v0.9.xy` in [our Substrate](https://github.com/duniter/substrate/)
* Set the upstream repository: `git remote add upstream git@github.com:paritytech/polkadot-sdk.git`
2. Create a new branch `duniter-substrate-v0.9.xy`
* Fetch the latest released version: `git fetch --tag polkadot-v1.9.0`
3. Cherry-pick `3ad5e1a1fdac5398d4911272a34e1f16c1bdd8f0`, `87ef489034ca2b15c4f30da387e06b1f6716d9a2` and `c36ab4f32454318a47777b24b6533c44121fc10b`
* Create a new branch: `git checkout -b duniter-polkadot-v1.9.0`
4. Run `cargo check` to check the cherry-picking
* 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`
* Clone the repository: `git clone git@github.com:duniter/subxt.git`
2. Create a new branch `duniter-substrate-v0.9.32`
* Set the upstream repository: `git remote add upstream git@github.com:paritytech/subxt.git`
3. Fetch the [upstream repository](https://github.com/paritytech/subxt)
* 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.
4. Rebase on an upstream stable branch matching the wanted version
* 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`
* 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' {} +`.
2. Update the `rust-toolchain` file according to [Polkadot release notes](https://github.com/paritytech/polkadot/releases)
* 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).
* 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
At this point, two cases may arise:
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.
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.
* 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.
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`.
\ No newline at end of file
* 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.
