Stabilize VersionedMigration (#1503)

`VersionedMigration` has become somewhat widely used for handling
version bumps in migrations the last few months.

It is currently behind the `experimental` feature flag, requiring every
pallet that writes a new migration with version bumps to set up the
`experimental` flag in their own Cargo.tomls, and also for every runtime
using these pallets to explicitly enable the `experimental` flag for
each pallet.

This is becoming quite verbose, and I can only see the number of pallets
requiring the experimental flag increasing for no other reason than
using what has become a commonly used feature.

Additionally, I'm writing migration docs and would like to avoid
stepping through how to use the `experimental` feature to get
`VersionedMigration` working.

Since the feature has been used in production for some time now without
any reported issues, is becoming commonly used and ready to advertise in
docs, I feel this is a good time to make it non-experimental.

polkadot/runtime/common/Cargo.toml

@@ -64,7 +64,6 @@ test-helpers = { package = "polkadot-primitives-test-helpers", path = "../../pri
 
 [features]
 default = [ "std" ]
-experimental = [ "frame-support/experimental" ]
 no_std = []
 std = [
 	"bitvec/std",

polkadot/runtime/common/src/assigned_slots/migration.rs

@@ -63,7 +63,6 @@ pub mod v1 {
 	/// [`MigrateToV1`] wrapped in a
 	/// [`VersionedMigration`](frame_support::migrations::VersionedMigration), ensuring the
 	/// migration is only performed when on-chain version is 0.
-	#[cfg(feature = "experimental")]
 	pub type VersionCheckedMigrateToV1<T> = frame_support::migrations::VersionedMigration<
 		0,
 		1,

polkadot/runtime/common/src/paras_registrar/migration.rs

@@ -60,7 +60,6 @@ impl<T: Config, UnlockParaIds: Contains<ParaId>> OnRuntimeUpgrade
 	}
 }
 
-#[cfg(feature = "experimental")]
 pub type VersionCheckedMigrateToV1<T, UnlockParaIds> =
 	frame_support::migrations::VersionedMigration<
 		0,

polkadot/runtime/kusama/Cargo.toml

@@ -77,7 +77,7 @@ pallet-recovery = { path = "../../../substrate/frame/recovery", default-features
 pallet-referenda = { path = "../../../substrate/frame/referenda", default-features = false }
 pallet-scheduler = { path = "../../../substrate/frame/scheduler", default-features = false }
 pallet-session = { path = "../../../substrate/frame/session", default-features = false }
-pallet-society = { path = "../../../substrate/frame/society", default-features = false, features = ["experimental"] }
+pallet-society = { path = "../../../substrate/frame/society", default-features = false }
 frame-support = { path = "../../../substrate/frame/support", default-features = false }
 pallet-staking = { path = "../../../substrate/frame/staking", default-features = false }
 pallet-state-trie-migration = { path = "../../../substrate/frame/state-trie-migration", default-features = false }
@@ -103,7 +103,7 @@ frame-system-benchmarking = { path = "../../../substrate/frame/system/benchmarki
 pallet-election-provider-support-benchmarking = { path = "../../../substrate/frame/election-provider-support/benchmarking", default-features = false, optional = true }
 hex-literal = "0.4.1"
 
-runtime-common = { package = "polkadot-runtime-common", path = "../common", default-features = false, features = ["experimental"] }
+runtime-common = { package = "polkadot-runtime-common", path = "../common", default-features = false }
 runtime-parachains = { package = "polkadot-runtime-parachains", path = "../parachains", default-features = false }
 primitives = { package = "polkadot-primitives", path = "../../primitives", default-features = false }
 

polkadot/runtime/polkadot/Cargo.toml

@@ -82,7 +82,7 @@ pallet-whitelist = { path = "../../../substrate/frame/whitelist", default-featur
 pallet-vesting = { path = "../../../substrate/frame/vesting", default-features = false }
 pallet-utility = { path = "../../../substrate/frame/utility", default-features = false }
 frame-election-provider-support = { path = "../../../substrate/frame/election-provider-support", default-features = false }
-pallet-xcm = { path = "../../xcm/pallet-xcm", default-features = false, features=["experimental"] }
+pallet-xcm = { path = "../../xcm/pallet-xcm", default-features = false }
 pallet-xcm-benchmarks = { path = "../../xcm/pallet-xcm-benchmarks", default-features = false, optional = true }
 
 frame-benchmarking = { path = "../../../substrate/frame/benchmarking", default-features = false, optional = true }
@@ -94,7 +94,7 @@ pallet-session-benchmarking = { path = "../../../substrate/frame/session/benchma
 pallet-nomination-pools-benchmarking = { path = "../../../substrate/frame/nomination-pools/benchmarking", default-features = false, optional = true }
 hex-literal = { version = "0.4.1", optional = true }
 
-runtime-common = { package = "polkadot-runtime-common", path = "../common", default-features = false, features = ["experimental"] }
+runtime-common = { package = "polkadot-runtime-common", path = "../common", default-features = false }
 runtime-parachains = { package = "polkadot-runtime-parachains", path = "../parachains", default-features = false }
 primitives = { package = "polkadot-primitives", path = "../../primitives", default-features = false }
 

polkadot/runtime/rococo/Cargo.toml

@@ -65,7 +65,7 @@ pallet-proxy = { path = "../../../substrate/frame/proxy", default-features = fal
 pallet-recovery = { path = "../../../substrate/frame/recovery", default-features = false }
 pallet-scheduler = { path = "../../../substrate/frame/scheduler", default-features = false }
 pallet-session = { path = "../../../substrate/frame/session", default-features = false }
-pallet-society = { path = "../../../substrate/frame/society", default-features = false, features = ["experimental"] }
+pallet-society = { path = "../../../substrate/frame/society", default-features = false }
 pallet-sudo = { path = "../../../substrate/frame/sudo", default-features = false }
 frame-support = { path = "../../../substrate/frame/support", default-features = false }
 pallet-staking = { path = "../../../substrate/frame/staking", default-features = false }
@@ -76,15 +76,15 @@ pallet-tips = { path = "../../../substrate/frame/tips", default-features = false
 pallet-treasury = { path = "../../../substrate/frame/treasury", default-features = false }
 pallet-utility = { path = "../../../substrate/frame/utility", default-features = false }
 pallet-vesting = { path = "../../../substrate/frame/vesting", default-features = false }
-pallet-xcm = { path = "../../xcm/pallet-xcm", default-features = false, features=["experimental"] }
+pallet-xcm = { path = "../../xcm/pallet-xcm", default-features = false }
 pallet-xcm-benchmarks = { path = "../../xcm/pallet-xcm-benchmarks", default-features = false, optional = true }
 
 frame-benchmarking = { path = "../../../substrate/frame/benchmarking", default-features = false, optional = true }
 frame-try-runtime = { path = "../../../substrate/frame/try-runtime", default-features = false, optional = true }
 frame-system-benchmarking = { path = "../../../substrate/frame/system/benchmarking", default-features = false, optional = true }
 hex-literal = { version = "0.4.1" }
 
-runtime-common = { package = "polkadot-runtime-common", path = "../common", default-features = false, features = ["experimental"] }
+runtime-common = { package = "polkadot-runtime-common", path = "../common", default-features = false }
 runtime-parachains = { package = "polkadot-runtime-parachains", path = "../parachains", default-features = false }
 primitives = { package = "polkadot-primitives", path = "../../primitives", default-features = false }
 polkadot-parachain-primitives = { path = "../../parachain", default-features = false }

polkadot/runtime/westend/Cargo.toml

@@ -83,7 +83,7 @@ pallet-nomination-pools-runtime-api = { path = "../../../substrate/frame/nominat
 pallet-treasury = { path = "../../../substrate/frame/treasury", default-features = false }
 pallet-utility = { path = "../../../substrate/frame/utility", default-features = false }
 pallet-vesting = { path = "../../../substrate/frame/vesting", default-features = false }
-pallet-xcm = { path = "../../xcm/pallet-xcm", default-features = false, features=["experimental"] }
+pallet-xcm = { path = "../../xcm/pallet-xcm", default-features = false }
 pallet-xcm-benchmarks = { path = "../../xcm/pallet-xcm-benchmarks", default-features = false, optional = true }
 
 frame-benchmarking = { path = "../../../substrate/frame/benchmarking", default-features = false, optional = true }
@@ -95,7 +95,7 @@ pallet-offences-benchmarking = { path = "../../../substrate/frame/offences/bench
 pallet-session-benchmarking = { path = "../../../substrate/frame/session/benchmarking", default-features = false, optional = true }
 hex-literal = { version = "0.4.1", optional = true }
 
-runtime-common = { package = "polkadot-runtime-common", path = "../common", default-features = false, features = ["experimental"] }
+runtime-common = { package = "polkadot-runtime-common", path = "../common", default-features = false }
 primitives = { package = "polkadot-primitives", path = "../../primitives", default-features = false }
 polkadot-parachain-primitives = { path = "../../parachain", default-features = false }
 runtime-parachains = { package = "polkadot-runtime-parachains", path = "../parachains", default-features = false }

polkadot/xcm/pallet-xcm/Cargo.toml

@@ -32,8 +32,6 @@ xcm-builder = { package = "staging-xcm-builder", path = "../xcm-builder" }
 
 [features]
 default = [ "std" ]
-# Enable `VersionedMigration` for the migrations using the experimental feature.
-experimental = [ "frame-support/experimental" ]
 std = [
 	"bounded-collections/std",
 	"codec/std",

polkadot/xcm/pallet-xcm/src/migration.rs

@@ -65,7 +65,6 @@ pub mod v1 {
 	///
 	/// Wrapped in [`frame_support::migrations::VersionedMigration`] so the pre/post checks don't
 	/// begin failing after the upgrade is enacted on-chain.
-	#[cfg(feature = "experimental")]
 	pub type VersionCheckedMigrateToV1<T> = frame_support::migrations::VersionedMigration<
 		0,
 		1,

substrate/frame/society/Cargo.toml

@@ -34,8 +34,6 @@ sp-io = { path = "../../primitives/io" }
 
 [features]
 default = [ "std" ]
-# Enable `VersionedMigration` for migrations using this feature.
-experimental = [ "frame-support/experimental" ]
 std = [
 	"codec/std",
 	"frame-benchmarking?/std",

substrate/frame/society/src/migrations.rs

@@ -95,7 +95,6 @@ impl<
 
 /// [`VersionUncheckedMigrateToV2`] wrapped in a [`frame_support::migrations::VersionedMigration`],
 /// ensuring the migration is only performed when on-chain version is 0.
-#[cfg(feature = "experimental")]
 pub type VersionCheckedMigrateToV2<T, I, PastPayouts> =
 	frame_support::migrations::VersionedMigration<
 		0,

substrate/frame/support/src/migrations.rs

@@ -24,9 +24,7 @@ use sp_core::Get;
 use sp_io::{hashing::twox_128, storage::clear_prefix, KillStorageResult};
 use sp_std::marker::PhantomData;
 
-/// EXPERIMENTAL: The API of this feature may change.
-///
-/// Make it easier to write versioned runtime upgrades.
+/// Handles storage migration pallet versioning.
 ///
 /// [`VersionedMigration`] allows developers to write migrations without worrying about checking and
 /// setting storage versions. Instead, the developer wraps their migration in this struct which
@@ -69,14 +67,12 @@ use sp_std::marker::PhantomData;
 /// 	// other migrations...
 /// );
 /// ```
-#[cfg(feature = "experimental")]
 pub struct VersionedMigration<const FROM: u16, const TO: u16, Inner, Pallet, Weight> {
 	_marker: PhantomData<(Inner, Pallet, Weight)>,
 }
 
 /// A helper enum to wrap the pre_upgrade bytes like an Option before passing them to post_upgrade.
 /// This enum is used rather than an Option to make the API clearer to the developer.
-#[cfg(feature = "experimental")]
 #[derive(codec::Encode, codec::Decode)]
 pub enum VersionedPostUpgradeData {
 	/// The migration ran, inner vec contains pre_upgrade data.
@@ -91,7 +87,6 @@ pub enum VersionedPostUpgradeData {
 /// version of the pallets storage matches `From`, and after the upgrade set the on-chain storage to
 /// `To`. If the versions do not match, it writes a log notifying the developer that the migration
 /// is a noop.
-#[cfg(feature = "experimental")]
 impl<
 		const FROM: u16,
 		const TO: u16,

substrate/frame/support/test/tests/versioned_migration.rs

@@ -17,7 +17,7 @@
 
 //! Tests for [`VersionedMigration`]
 
-#![cfg(all(feature = "experimental", feature = "try-runtime"))]
+#![cfg(feature = "try-runtime")]
 
 use frame_support::{
 	construct_runtime, derive_impl,