Skip to content
Snippets Groups Projects
Unverified Commit cdbff371 authored by bgallois's avatar bgallois
Browse files

upgrade documentation

parent 352d0317
No related branches found
No related tags found
No related merge requests found
Pipeline #36606 passed
# 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.
0% Loading or .
You are about to add 0 people to the discussion. Proceed with caution.
Please register or to comment