Staging API declaration and stubs

primitives/src/lib.rs

@@ -19,4 +19,14 @@
 #![warn(missing_docs)]
 #![cfg_attr(not(feature = "std"), no_std)]
 
+// `v2` is currently the latest stable version of the runtime API.
 pub mod v2;
+
+// The 'staging' version is special - while other versions are set in stone,
+// the staging version is malleable. Once it's released, it gets the next
+// version number.
+pub mod vstaging;
+
+// `runtime_api` contains the actual API implementation. It contains stable and
+// unstable functions.
+pub mod runtime_api;

primitives/src/runtime_api.rs

@@ -14,6 +14,44 @@
 // You should have received a copy of the GNU General Public License
 // along with Polkadot.  If not, see <http://www.gnu.org/licenses/>.
 
+//! Runtime API module declares the `trait ParachainHost` which us part
+//! of the Runtime API exposed from the Runtime to the Host.
+//!
+//! The functions in trait ParachainHost` can be part of the stable API
+//! (which is versioned) or they can be unstable (aka staging functions).
+//!
+//! All stable API functions should use primitives from the latest version.
+//! In the time of writing of this document - this is v2. So for example:
+//! ```rust
+//! fn validators() -> Vec<v2::ValidatorId>;
+//! ```
+//! indicates a function from the stable v2 API.
+//!
+//! On the other hand a staging function might look like this:
+//! ```rust
+//! fn get_session_disputes() -> Vec<(vstaging::SessionIndex, vstaging::CandidateHash, vstaging::DisputeState<vstaging::BlockNumber>)>;
+//! ```
+//! or this:
+//! ```rust
+//! fn unstable_get_session_disputes() -> Vec<(vstaging::SessionIndex, vstaging::CandidateHash, vstaging::DisputeState<vstaging::BlockNumber>)>;
+//! ```
+//! In the second example the function is prefixed with `unstable_`. This
+//! is optional but the important moment is the use of primitives from
+//! `vstaging`.
+//!
+//! How a staging function becomes stable?
+//!
+//! Once a staging function is ready to be versioned the `changed_in` macro
+//! can be used to rename it and version it. For the example above:
+//! ```rust
+//! fn get_session_disputes() -> Vec<(v3::SessionIndex, v3::CandidateHash, v3::DisputeState<v3::BlockNumber>)>;
+//!
+//! #[changed_in(2)]
+//! fn unstable_get_session_disputes() -> Vec<(vstaging::SessionIndex, vstaging::CandidateHash, vstaging::DisputeState<vstaging::BlockNumber>)>;
+//! ```
+//! For more details about how the API versioning works refer to `spi_api`
+//! documentation [here](https://docs.substrate.io/rustdocs/latest/sp_api/macro.decl_runtime_apis.html).
+
 use crate::v2;
 use parity_scale_codec::{Decode, Encode};
 use polkadot_core_primitives as pcp;

primitives/src/vstaging/mod.rs

@@ -0,0 +1,19 @@
+// Copyright 2017-2021 Parity Technologies (UK) Ltd.
+// This file is part of Polkadot.
+
+// Polkadot is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+
+// Polkadot is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+
+// You should have received a copy of the GNU General Public License
+// along with Polkadot.  If not, see <http://www.gnu.org/licenses/>.
+
+//! Staging Primitives.
+
+// Put any primitives used by staging API functions here

runtime/parachains/src/runtime_api_impl/mod.rs

@@ -21,3 +21,4 @@
 //! to a v2 would be done.
 
 pub mod v2;
+pub mod vstaging;

runtime/parachains/src/runtime_api_impl/vstaging.rs

@@ -0,0 +1,17 @@
+// Copyright 2017-2022 Parity Technologies (UK) Ltd.
+// This file is part of Polkadot.
+
+// Polkadot is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+
+// Polkadot is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+
+// You should have received a copy of the GNU General Public License
+// along with Polkadot.  If not, see <http://www.gnu.org/licenses/>.
+
+// Put implementations of functions from staging API here.