pezkuwichain/pezkuwi-subxt
1
0
Fork 0
mirror of https://github.com/pezkuwichain/pezkuwi-subxt.git synced 2026-04-26 16:57:58 +00:00
Code Issues Packages Projects Releases Wiki Activity

Add some docs about runtime migration best practices (#9837)

Browse Source 
* Add some docs about runtime migration best practices as well.

* Update docs/CONTRIBUTING.adoc

* Update docs/CONTRIBUTING.adoc

Co-authored-by: Chevdor <chevdor@users.noreply.github.com>

Co-authored-by: Chevdor <chevdor@users.noreply.github.com>
This commit is contained in:
Kian Paimani
2021-09-23 09:20:37 +01:00
committed by GitHub
parent 5922da95e5
commit ea0117af5d
2 changed files with 43 additions and 6 deletions
Download Patch File Download Diff File Expand all files Collapse all files
substrate/utils/frame/try-runtime/cli/src/lib.rs
+41 -3
View File
@@ -29,9 +29,9 @@
//!
//! Some resources about the above:
//!
//! 1. https://substrate.dev/docs/en/knowledgebase/integrate/try-runtime
//! 2. https://www.crowdcast.io/e/substrate-seminar/41
//! 3. https://substrate.dev/docs/en/knowledgebase/advanced/executor
//! 1. <https://substrate.dev/docs/en/knowledgebase/integrate/try-runtime>
//! 2. <https://www.crowdcast.io/e/substrate-seminar/41>
//! 3. <https://substrate.dev/docs/en/knowledgebase/advanced/executor>
//!
//! ---
//!
@@ -117,6 +117,44 @@
//!
//! Note that *none* of the try-runtime operations need unsafe RPCs.
//!
//! ## Migration Best Practices
//!
//! One of the main use-cases of try-runtime is using it for testing storage migrations. The
//! following points makes sure you can *effectively* test your migrations with try-runtime.
//!
//! #### Adding pre/post hooks
//!
//! One of the gems that come only in the `try-runtime` feature flag is the `pre_upgrade` and
//! `post_upgrade` hooks for [`OnRuntimeUpgrade`]. This trait is implemented either inside the
//! pallet, or manually in a runtime, to define a migration. In both cases, these functions can be
//! added, given the right flag:
//!
//! ```ignore
//! #[cfg(feature = try-runtime)]
//! fn pre_upgrade() -> Result<(), &'static str> {}
//!
//! #[cfg(feature = try-runtime)]
//! fn post_upgrade() -> Result<(), &'static str> {}
//! ```
//!
//! (The pallet macro syntax will support this simply as a part of `#[pallet::hooks]`).
//!
//! These hooks allow you to execute some code, only within the `on-runtime-upgrade` command, before
//! and after the migration. If any data needs to be temporarily stored between the pre/post
//! migration hooks, [`OnRuntimeUpgradeHelpersExt`] can help with that.
//!
//! #### Logging
//!
//! It is super helpful to make sure your migration code uses logging (always with a `runtime` log
//! target prefix, e.g. `runtime::balance`) and state exactly at which stage it is, and what it is
//! doing.
//!
//! #### Guarding migrations
//!
//! Always make sure that any migration code is guarded either by [`StorageVersion`], or by some
//! custom storage item, so that it is NEVER executed twice, even if the code lives in two
//! consecutive runtimes.
//!
//! ## Examples
//!
//! Run the migrations of the local runtime on the state of polkadot, from the polkadot repo where