Introduce Polkadot-Sdk developer_hub (paritytech#2102)

This PR introduces the new crate `developer_hub` into the polkadot-sdk repo. The vision for the developer-hub crate is detailed in [this document](https://docs.google.com/document/d/1XLLkFNE8v8HLvZpI2rzsa8N2IN1FcKntc8q-Sc4xBAk/edit?usp=sharing). <img width="1128" alt="Screenshot 2023-11-02 at 10 45 48" src="https://github.com/paritytech/polkadot-sdk/assets/5588131/1e12b60f-fef5-42c4-8503-a3ba234077c3"> Other than adding the new crate, it also does the following: * Remove the `substrate` crate, as there is now a unique umbrella crate for multiple things in `developer_hub::polkadot_sdk`. * (backport candidate) A minor change to `frame-support` macros that allows `T::RuntimeOrigin` to also be acceptable as the origin type. * (backport candidate) A minor change to `frame-system` that allows us to deposit events at genesis because now the real genesis config is generated via wasm, and we can safely assume `cfg!(feature = "std")` means only testing. related to paritytech#62. * (backport candidate) Introduces a small `read_events_for_pallet` to `frame_system` for easier event reading in tests. * From paritytech/polkadot-sdk-docs#31, it takes action on improving the `pallet::call` docs. * From paritytech/polkadot-sdk-docs#31, it takes action on improving the `UncheckedExtrinsic` docs. ## Way Forward First, a version of this is deployed temporarily [here](https://blog.kianenigma.nl/polkadot-sdk/developer_hub/index.html). I will keep it up to date on a daily basis. ### This Pull Request I see two ways forward: 1. We acknowledge that everything in `developer-hub` is going to be WIP, and merge this asap. We should not yet use links to this crate anywhere. 2. We make this be the feature branch, make PRs against this, and either gradually backport it, or only merge to master once it is done. I am personally in favor of option 1. If we stick to option 2, we need a better way to deploy a staging version of this to gh-pages. ### Issue Tracking The main issues related to the future of `developer_hub` are: - paritytech/polkadot-sdk-docs#31 - paritytech/polkadot-sdk-docs#4 - paritytech/polkadot-sdk-docs#26 - paritytech/polkadot-sdk-docs#32 - paritytech/polkadot-sdk-docs#36 ### After This Pull Request - [ ] create a redirect for https://paritytech.github.io/polkadot-sdk/master/substrate/ - [x] analytics - [ ] link checker - [ ] the matter of publishing, and how all of these relative links for when we do, that is still an open question. There is section on this in the landing page. - [ ] updated https://paritytech.github.io/ --------- Co-authored-by: Liam Aharon <[email protected]> Co-authored-by: Juan Girini <[email protected]> Co-authored-by: bader y <[email protected]> Co-authored-by: Sebastian Kunert <[email protected]> Co-authored-by: James Wilson <[email protected]> Co-authored-by: Michal Kucharczyk <[email protected]>
duniter · Nov 30, 2023 · 3a6d7cb · 3a6d7cb
1 parent d6cc8de
commit 3a6d7cb
Show file tree

Hide file tree

Showing 35 changed files with 332 additions and 430 deletions.
diff --git a/substrate/Cargo.toml b/substrate/Cargo.toml
diff --git a/substrate/client/allocator/src/lib.rs b/substrate/client/allocator/src/lib.rs
@@ -18,7 +18,7 @@
 //! Collection of allocator implementations.
 //!
 //! This crate provides the following allocator implementations:
-//! - A freeing-bump allocator: [`FreeingBumpHeapAllocator`](freeing_bump::FreeingBumpHeapAllocator)
+//! - A freeing-bump allocator: [`FreeingBumpHeapAllocator`]
 
 #![warn(missing_docs)]
 

diff --git a/substrate/client/executor/src/lib.rs b/substrate/client/executor/src/lib.rs
@@ -58,7 +58,7 @@ pub use sc_executor_wasmtime::InstantiationStrategy as WasmtimeInstantiationStra
 
 /// Extracts the runtime version of a given runtime code.
 pub trait RuntimeVersionOf {
-	/// Extract [`RuntimeVersion`](sp_version::RuntimeVersion) of the given `runtime_code`.
+	/// Extract [`RuntimeVersion`] of the given `runtime_code`.
 	fn runtime_version(
 		&self,
 		ext: &mut dyn Externalities,

diff --git a/substrate/frame/balances/src/lib.rs b/substrate/frame/balances/src/lib.rs
@@ -49,8 +49,7 @@
 //! - **Total Issuance:** The total number of units in existence in a system.
 //!
 //! - **Reaping an account:** The act of removing an account by resetting its nonce. Happens after
-//!   its
-//! total balance has become zero (or, strictly speaking, less than the Existential Deposit).
+//!   its total balance has become zero (or, strictly speaking, less than the Existential Deposit).
 //!
 //! - **Free Balance:** The portion of a balance that is not reserved. The free balance is the only
 //!   balance that matters for most operations.
@@ -59,24 +58,23 @@
 //!   Reserved balance can still be slashed, but only after all the free balance has been slashed.
 //!
 //! - **Imbalance:** A condition when some funds were credited or debited without equal and opposite
-//!   accounting
-//! (i.e. a difference between total issuance and account balances). Functions that result in an
-//! imbalance will return an object of the `Imbalance` trait that can be managed within your runtime
-//! logic. (If an imbalance is simply dropped, it should automatically maintain any book-keeping
-//! such as total issuance.)
+//!   accounting (i.e. a difference between total issuance and account balances). Functions that
+//! result in an imbalance will return an object of the `Imbalance` trait that can be managed within
+//! your runtime logic. (If an imbalance is simply dropped, it should automatically maintain any
+//! book-keeping such as total issuance.)
 //!
 //! - **Lock:** A freeze on a specified amount of an account's free balance until a specified block
-//!   number. Multiple
-//! locks always operate over the same funds, so they "overlay" rather than "stack".
+//!   number. Multiple locks always operate over the same funds, so they "overlay" rather than
+//! "stack".
 //!
 //! ### Implementations
 //!
 //! The Balances pallet provides implementations for the following traits. If these traits provide
 //! the functionality that you need, then you can avoid coupling with the Balances pallet.
 //!
-//! - [`Currency`](frame_support::traits::Currency): Functions for dealing with a
+//! - [`Currency`]: Functions for dealing with a
 //! fungible assets system.
-//! - [`ReservableCurrency`](frame_support::traits::ReservableCurrency):
+//! - [`ReservableCurrency`]
 //! - [`NamedReservableCurrency`](frame_support::traits::NamedReservableCurrency):
 //! Functions for dealing with assets that can be reserved from an account.
 //! - [`LockableCurrency`](frame_support::traits::LockableCurrency): Functions for
@@ -105,7 +103,7 @@
 //! ```
 //! use frame_support::traits::Currency;
 //! # pub trait Config: frame_system::Config {
-//! # 	type Currency: Currency<Self::AccountId>;
+//! #   type Currency: Currency<Self::AccountId>;
 //! # }
 //!
 //! pub type BalanceOf<T> = <<T as Config>::Currency as Currency<<T as frame_system::Config>::AccountId>>::Balance;
@@ -120,26 +118,26 @@
 //! use frame_support::traits::{WithdrawReasons, LockableCurrency};
 //! use sp_runtime::traits::Bounded;
 //! pub trait Config: frame_system::Config {
-//! 	type Currency: LockableCurrency<Self::AccountId, Moment=frame_system::pallet_prelude::BlockNumberFor<Self>>;
+//!     type Currency: LockableCurrency<Self::AccountId, Moment=frame_system::pallet_prelude::BlockNumberFor<Self>>;
 //! }
 //! # struct StakingLedger<T: Config> {
-//! # 	stash: <T as frame_system::Config>::AccountId,
-//! # 	total: <<T as Config>::Currency as frame_support::traits::Currency<<T as frame_system::Config>::AccountId>>::Balance,
-//! # 	phantom: std::marker::PhantomData<T>,
+//! #   stash: <T as frame_system::Config>::AccountId,
+//! #   total: <<T as Config>::Currency as frame_support::traits::Currency<<T as frame_system::Config>::AccountId>>::Balance,
+//! #   phantom: std::marker::PhantomData<T>,
 //! # }
 //! # const STAKING_ID: [u8; 8] = *b"staking ";
 //!
 //! fn update_ledger<T: Config>(
-//! 	controller: &T::AccountId,
-//! 	ledger: &StakingLedger<T>
+//!     controller: &T::AccountId,
+//!     ledger: &StakingLedger<T>
 //! ) {
-//! 	T::Currency::set_lock(
-//! 		STAKING_ID,
-//! 		&ledger.stash,
-//! 		ledger.total,
-//! 		WithdrawReasons::all()
-//! 	);
-//! 	// <Ledger<T>>::insert(controller, ledger); // Commented out as we don't have access to Staking's storage here.
+//!     T::Currency::set_lock(
+//!         STAKING_ID,
+//!         &ledger.stash,
+//!         ledger.total,
+//!         WithdrawReasons::all()
+//!     );
+//!     // <Ledger<T>>::insert(controller, ledger); // Commented out as we don't have access to Staking's storage here.
 //! }
 //! # fn main() {}
 //! ```

diff --git a/substrate/frame/bounties/src/migrations/v4.rs b/substrate/frame/bounties/src/migrations/v4.rs
@@ -110,7 +110,7 @@ pub fn migrate<
 }
 
 /// Some checks prior to migration. This can be linked to
-/// [`frame_support::traits::OnRuntimeUpgrade::pre_upgrade`] for further testing.
+/// `frame_support::traits::OnRuntimeUpgrade::pre_upgrade` for further testing.
 ///
 /// Panics if anything goes wrong.
 pub fn pre_migration<T: pallet_bounties::Config, P: GetStorageVersion + 'static, N: AsRef<str>>(
@@ -164,7 +164,7 @@ pub fn pre_migration<T: pallet_bounties::Config, P: GetStorageVersion + 'static,
 }
 
 /// Some checks for after migration. This can be linked to
-/// [`frame_support::traits::OnRuntimeUpgrade::post_upgrade`] for further testing.
+/// `frame_support::traits::OnRuntimeUpgrade::post_upgrade` for further testing.
 ///
 /// Panics if anything goes wrong.
 pub fn post_migration<T: pallet_bounties::Config, P: GetStorageVersion, N: AsRef<str>>(

diff --git a/substrate/frame/collective/src/migrations/v4.rs b/substrate/frame/collective/src/migrations/v4.rs
@@ -76,7 +76,7 @@ pub fn migrate<T: frame_system::Config, P: GetStorageVersion + PalletInfoAccess,
 }
 
 /// Some checks prior to migration. This can be linked to
-/// [`frame_support::traits::OnRuntimeUpgrade::pre_upgrade`] for further testing.
+/// `frame_support::traits::OnRuntimeUpgrade::pre_upgrade` for further testing.
 ///
 /// Panics if anything goes wrong.
 pub fn pre_migrate<P: GetStorageVersion + PalletInfoAccess, N: AsRef<str>>(old_pallet_name: N) {
@@ -104,7 +104,7 @@ pub fn pre_migrate<P: GetStorageVersion + PalletInfoAccess, N: AsRef<str>>(old_p
 }
 
 /// Some checks for after migration. This can be linked to
-/// [`frame_support::traits::OnRuntimeUpgrade::post_upgrade`] for further testing.
+/// `frame_support::traits::OnRuntimeUpgrade::post_upgrade` for further testing.
 ///
 /// Panics if anything goes wrong.
 pub fn post_migrate<P: GetStorageVersion + PalletInfoAccess, N: AsRef<str>>(old_pallet_name: N) {

diff --git a/substrate/frame/election-provider-multi-phase/src/mock.rs b/substrate/frame/election-provider-multi-phase/src/mock.rs
@@ -80,11 +80,7 @@ frame_election_provider_support::generate_solution_type!(
 
 /// All events of this pallet.
 pub(crate) fn multi_phase_events() -> Vec<super::Event<Runtime>> {
-	System::events()
-		.into_iter()
-		.map(|r| r.event)
-		.filter_map(|e| if let RuntimeEvent::MultiPhase(inner) = e { Some(inner) } else { None })
-		.collect::<Vec<_>>()
+	System::read_events_for_pallet::<super::Event<Runtime>>()
 }
 
 /// To from `now` to block `n`.

diff --git a/substrate/frame/elections-phragmen/src/migrations/v4.rs b/substrate/frame/elections-phragmen/src/migrations/v4.rs
@@ -69,7 +69,7 @@ pub fn migrate<T: crate::Config, N: AsRef<str>>(new_pallet_name: N) -> Weight {
 }
 
 /// Some checks prior to migration. This can be linked to
-/// [`frame_support::traits::OnRuntimeUpgrade::pre_upgrade`] for further testing.
+/// `frame_support::traits::OnRuntimeUpgrade::pre_upgrade` for further testing.
 ///
 /// Panics if anything goes wrong.
 pub fn pre_migration<T: crate::Config, N: AsRef<str>>(new: N) {
@@ -97,7 +97,7 @@ pub fn pre_migration<T: crate::Config, N: AsRef<str>>(new: N) {
 }
 
 /// Some checks for after migration. This can be linked to
-/// [`frame_support::traits::OnRuntimeUpgrade::post_upgrade`] for further testing.
+/// `frame_support::traits::OnRuntimeUpgrade::post_upgrade` for further testing.
 ///
 /// Panics if anything goes wrong.
 pub fn post_migration<T: crate::Config>() {

diff --git a/substrate/frame/elections-phragmen/src/migrations/v5.rs b/substrate/frame/elections-phragmen/src/migrations/v5.rs
@@ -71,7 +71,7 @@ pub fn pre_migrate_fn<T: Config>(to_migrate: Vec<T::AccountId>) -> Box<dyn Fn()
 }
 
 /// Some checks for after migration. This can be linked to
-/// [`frame_support::traits::OnRuntimeUpgrade::post_upgrade`] for further testing.
+/// `frame_support::traits::OnRuntimeUpgrade::post_upgrade` for further testing.
 ///
 /// Panics if anything goes wrong.
 pub fn post_migrate<T: crate::Config>() {

diff --git a/substrate/frame/examples/kitchensink/src/lib.rs b/substrate/frame/examples/kitchensink/src/lib.rs
@@ -292,9 +292,8 @@ pub mod pallet {
 		}
 	}
 
-	/// Allows you to define an enum on the pallet which will then instruct
-	/// `construct_runtime` to amalgamate all similarly-named enums from other
-	/// pallets into an aggregate enum.
+	/// Allows you to define an enum on the pallet which will then instruct `construct_runtime` to
+	/// amalgamate all similarly-named enums from other pallets into an aggregate enum.
 	#[pallet::composite_enum]
 	pub enum HoldReason {
 		Staking,

diff --git a/substrate/frame/fast-unstake/src/types.rs b/substrate/frame/fast-unstake/src/types.rs
@@ -39,6 +39,7 @@ impl<T: Config> frame_support::traits::Get<u32> for MaxChecking<T> {
 	}
 }
 
+#[docify::export]
 pub(crate) type BalanceOf<T> =
 	<<T as Config>::Currency as Currency<<T as frame_system::Config>::AccountId>>::Balance;
 /// An unstake request.

diff --git a/substrate/frame/grandpa/src/migrations/v4.rs b/substrate/frame/grandpa/src/migrations/v4.rs
@@ -63,7 +63,7 @@ pub fn migrate<T: crate::Config, N: AsRef<str>>(new_pallet_name: N) -> Weight {
 }
 
 /// Some checks prior to migration. This can be linked to
-/// [`frame_support::traits::OnRuntimeUpgrade::pre_upgrade`] for further testing.
+/// `frame_support::traits::OnRuntimeUpgrade::pre_upgrade` for further testing.
 ///
 /// Panics if anything goes wrong.
 pub fn pre_migration<T: crate::Config, N: AsRef<str>>(new: N) {
@@ -99,7 +99,7 @@ pub fn pre_migration<T: crate::Config, N: AsRef<str>>(new: N) {
 }
 
 /// Some checks for after migration. This can be linked to
-/// [`frame_support::traits::OnRuntimeUpgrade::post_upgrade`] for further testing.
+/// `frame_support::traits::OnRuntimeUpgrade::post_upgrade` for further testing.
 ///
 /// Panics if anything goes wrong.
 pub fn post_migration() {

diff --git a/substrate/frame/membership/src/migrations/v4.rs b/substrate/frame/membership/src/migrations/v4.rs
@@ -77,7 +77,7 @@ pub fn migrate<T: frame_system::Config, P: GetStorageVersion + PalletInfoAccess,
 }
 
 /// Some checks prior to migration. This can be linked to
-/// [`frame_support::traits::OnRuntimeUpgrade::pre_upgrade`] for further testing.
+/// `frame_support::traits::OnRuntimeUpgrade::pre_upgrade` for further testing.
 ///
 /// Panics if anything goes wrong.
 pub fn pre_migrate<P: GetStorageVersion, N: AsRef<str>>(old_pallet_name: N, new_pallet_name: N) {
@@ -105,7 +105,7 @@ pub fn pre_migrate<P: GetStorageVersion, N: AsRef<str>>(old_pallet_name: N, new_
 }
 
 /// Some checks for after migration. This can be linked to
-/// [`frame_support::traits::OnRuntimeUpgrade::post_upgrade`] for further testing.
+/// `frame_support::traits::OnRuntimeUpgrade::post_upgrade` for further testing.
 ///
 /// Panics if anything goes wrong.
 pub fn post_migrate<P: GetStorageVersion, N: AsRef<str>>(old_pallet_name: N, new_pallet_name: N) {

diff --git a/substrate/frame/session/src/historical/offchain.rs b/substrate/frame/session/src/historical/offchain.rs
@@ -17,13 +17,11 @@
 
 //! Off-chain logic for creating a proof based data provided by on-chain logic.
 //!
-//! Validator-set extracting an iterator from an off-chain worker stored list containing
-//! historical validator-sets.
-//! Based on the logic of historical slashing, but the validation is done off-chain.
+//! Validator-set extracting an iterator from an off-chain worker stored list containing historical
+//! validator-sets. Based on the logic of historical slashing, but the validation is done off-chain.
 //! Use [`fn store_current_session_validator_set_to_offchain()`](super::onchain) to store the
-//! required data to the offchain validator set.
-//! This is used in conjunction with [`ProvingTrie`](super::ProvingTrie) and
-//! the off-chain indexing API.
+//! required data to the offchain validator set. This is used in conjunction with [`ProvingTrie`]
+//! and the off-chain indexing API.
 
 use sp_runtime::{
 	offchain::storage::{MutateStorageError, StorageRetrievalError, StorageValueRef},

diff --git a/substrate/frame/src/lib.rs b/substrate/frame/src/lib.rs
@@ -15,10 +15,6 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
-//! > Made for [![polkadot]](https://polkadot.network)
-//!
-//! [polkadot]: https://img.shields.io/badge/polkadot-E6007A?style=for-the-badge&logo=polkadot&logoColor=white
-//!
 //! # FRAME
 //!
 //! ```no_compile
@@ -34,14 +30,21 @@
 //! > **F**ramework for **R**untime **A**ggregation of **M**odularized **E**ntities: Substrate's
 //! > State Transition Function (Runtime) Framework.
 //!
+//! ## Documentation
+//!
+//! See [`polkadot_sdk::frame`](../developer_hub/polkadot_sdk/frame_runtime/index.html).
+//!
 //! ## Warning: Experimental
 //!
 //! This crate and all of its content is experimental, and should not yet be used in production.
 //!
-//! ## Getting Started
+//! ## Underlying dependencies
 //!
-//! TODO: link to `developer_hub::polkadot_sdk::frame`. The `developer_hub` hasn't been published
-//! yet, this can be updated once it is linkable.
+//! This crate is an amalgamation of multiple other crates that are often used together to compose a
+//! pallet. It is not necessary to use it, and it may fall short for certain purposes.
+//!
+//! In short, this crate only re-exports types and traits from multiple sources. All of these
+//! sources are listed (and re-exported again) in [`deps`].
 
 #![cfg_attr(not(feature = "std"), no_std)]
 #![cfg(feature = "experimental")]
@@ -54,9 +57,19 @@
 /// `#[pallet::bar]` inside the mod.
 pub use frame_support::pallet;
 
+pub use frame_support::pallet_macros::{import_section, pallet_section};
+
 /// The logging library of the runtime. Can normally be the classic `log` crate.
 pub use log;
 
+/// A list of all macros used within the main [`pallet`] macro.
+///
+/// Note: All of these macros are "stubs" and not really usable outside `#[pallet] mod pallet { ..
+/// }`. They are mainly provided for documentation and IDE support.
+pub mod pallet_macros {
+	pub use frame_support::{derive_impl, pallet, pallet_macros::*};
+}
+
 /// The main prelude of FRAME.
 ///
 /// This prelude should almost always be the first line of code in any pallet or runtime.
@@ -78,9 +91,6 @@ pub mod prelude {
 	/// Pallet prelude of `frame-support`.
 	///
 	/// Note: this needs to revised once `frame-support` evolves.
-	// `frame-support` will be break down https://github.com/paritytech/polkadot-sdk/issues/127 and its reexports will
-	// most likely change. These wildcard reexportings can be optimized once `frame-support` has
-	// changed.
 	#[doc(no_inline)]
 	pub use frame_support::pallet_prelude::*;
 
@@ -156,6 +166,9 @@ pub mod runtime {
 		/// Types to define your runtime version.
 		pub use sp_version::{create_runtime_str, runtime_version, RuntimeVersion};
 
+		/// Macro to implement runtime APIs.
+		pub use sp_api::impl_runtime_apis;
+
 		#[cfg(feature = "std")]
 		pub use sp_version::NativeVersion;
 	}
@@ -180,9 +193,6 @@ pub mod runtime {
 		pub use sp_inherents::{CheckInherentsResult, InherentData};
 		pub use sp_runtime::ApplyExtrinsicResult;
 
-		/// Macro to implement runtime APIs.
-		pub use sp_api::impl_runtime_apis;
-
 		pub use frame_system_rpc_runtime_api::*;
 		pub use sp_api::{self, *};
 		pub use sp_block_builder::*;