#
pezkuwi_sdk_docs/
meta_contributing.rs

    1//! # Contribution
    2//!
    3//! The following sections cover more detailed information about this crate and how it should be
    4//! maintained.
    5//!
    6//! ## Why Rust Docs?
    7//!
    8//! We acknowledge that blockchain based systems, particularly a cutting-edge one like Pezkuwi SDK
    9//! is a software artifact that is complex, and rapidly evolving. This makes the task of documenting
    10//! it externally extremely difficult, especially with regards to making sure it is up-to-date.
    11//!
    12//! Consequently, we argue that the best hedge against this is to move as much of the documentation
    13//! near the source code as possible. This would further incentivize developers to keep the
    14//! documentation up-to-date, as the overhead is reduced by making sure everything is in one
    15//! repository, and everything being in `.rs` files.
    16//!
    17//! > This is not to say that a more visually appealing version of this crate (for example as an
    18//! > `md-book`) cannot exist, but it would be outside the scope of this crate.
    19//!
    20//! Moreover, we acknowledge that a major pain point has been not only outdated *concepts*, but also
    21//! *outdated code*. For this, we commit to making sure no code-snippet in this crate is left as
    22//! `///ignore` or `///no_compile`, making sure all code snippets are self-contained, compile-able,
    23//! and correct at every single revision of the entire repository.
    24//!
    25//! > This also allows us to have a clear versioning on the entire content of this crate. For every
    26//! commit of the Pezkuwi SDK, there would be one version of this crate that is guaranteed to be
    27//! correct.
    28//!
    29//! > To achieve this, we often use [`docify`](https://github.com/sam0x17/docify), a nifty invention
    30//! > of `@sam0x17`.
    31//!
    32//! Also see: <https://github.com/pezkuwichain/pezkuwi-sdk/issues/109>.
    33//!
    34//! ## Scope
    35//!
    36//! The above would NOT be attainable if we don't acknowledge that the scope of this crate MUST be
    37//! limited, or else its maintenance burden would be infeasible or not worthwhile. In short, future
    38//! maintainers should always strive to keep the content of this repository as minimal as possible.
    39//! Some of the following principles are specifically there to be the guidance for this.
    40//!
    41//! ## Principles
    42//!
    43//! The following guidelines are meant to be the guiding torch of those who contribute to this
    44//! crate.
    45//!
    46//! 1. 🔺 Ground Up: Information should be laid out in the most ground-up fashion. The lowest level
    47//!    (i.e. "ground") is Rust-docs. The highest level (i.e. "up") is "outside of this crate". In
    48//!    between lies [`reference_docs`] and [`guides`], from low to high. The point of this principle
    49//!    is to document as much of the information as possible in the lower level media, as it is
    50//!    easier to maintain and more reachable. Then, use excessive linking to back-link when writing
    51//!    in a more high level.
    52//!
    53//! > A prime example of this, the details of the FRAME storage APIs should NOT be explained in a
    54//! > high level tutorial. They should be explained in the rust-doc of the corresponding type or
    55//! > macro.
    56//!
    57//! 2. 🧘 Less is More: For reasons mentioned [above](#why-rust-docs), the more concise this crate
    58//!    is, the better.
    59//! 3. √ Don’t Repeat Yourself – DRY: A summary of the above two points. Authors should always
    60//!    strive to avoid any duplicate information. Every concept should ideally be documented in
    61//!    *ONE* place and one place only. This makes the task of maintaining topics significantly
    62//!    easier.
    63//!
    64//! > A prime example of this, the list of CLI arguments of a particular binary should not be
    65//! > documented in multiple places across this crate. It should be only be documented in the
    66//! > corresponding crate (e.g. `sc_cli`).
    67//!
    68//! > Moreover, this means that as a contributor, **it is your responsibility to have a grasp over
    69//! > what topics are already covered in this crate, and how you can build on top of the information
    70//! > that they already pose, rather than repeating yourself**.
    71//!
    72//! For more details see the [latest documenting
    73//! guidelines](https://github.com/pezkuwichain/pezkuwi-sdk/blob/master/docs/contributor/DOCUMENTATION_GUIDELINES.md).
    74//!
    75//! #### Example: Explaining `#[pallet::call]`
    76//!
    77//! <details>
    78//! <summary>
    79//! Let's consider the seemingly simple example of explaining to someone dead-simple code of a FRAME
    80//! call and see how we can use the above principles.
    81//! </summary>
    82//!
    83//!
    84//! ```
    85//! #[frame::pallet(dev_mode)]
    86//! pub mod pallet {
    87//! #   use frame::prelude::*;
    88//! #   #[pallet::config]
    89//! #   pub trait Config: frame_system::Config {}
    90//! #   #[pallet::pallet]
    91//! #   pub struct Pallet<T>(_);
    92//!     #[pallet::call]
    93//!     impl<T: Config> Pallet<T> {
    94//!         pub fn a_simple_call(origin: OriginFor<T>, data: u32) -> DispatchResult {
    95//!             ensure!(data > 10, "SomeStaticString");
    96//!             todo!();
    97//!         }
    98//!     }
    99//! }
    100//! ```
    101//!
    102//! * Before even getting started, what is with all of this `<T: Config>`? We link to
    103//! [`crate::reference_docs::trait_based_programming`].
    104//! * First, the name. Why is this called `pallet::call`? This goes back to `enum Call`, which is
    105//! explained in [`crate::reference_docs::frame_runtime_types`]. Build on top of this!
    106//! * Then, what is `origin`? Just an account id? [`crate::reference_docs::frame_origin`].
    107//! * Then, what is `DispatchResult`? Why is this called *dispatch*? Probably something that can be
    108//! explained in the documentation of [`frame::prelude::DispatchResult`].
    109//! * Why is `"SomeStaticString"` a valid error? Because there is implementation for it that you can
    110//!   see [here](frame::prelude::DispatchError#impl-From<%26'static+str>-for-DispatchError).
    111//!
    112//!
    113//! All of these are examples of underlying information that a contributor should:
    114//!
    115//! 1. Try and create and they are going along.
    116//! 2. Back-link to if they already exist.
    117//!
    118//! Of course, all of this is not set in stone as a either/or rule. Sometimes, it is necessary to
    119//! rephrase a concept in a new context.
    120//!
    121//! </details>
    122//!
    123//! ## `crates.io` and Publishing
    124//!
    125//! As it stands now, this crate cannot be published to crates.io because of its use of
    126//! [workspace-level `docify`](https://github.com/sam0x17/docify/issues/22). For now, we accept this
    127//! compromise, but in the long term, we should work towards finding a way to maintain different
    128//! revisions of this crate.
    129//!
    130//! ## Versioning
    131//!
    132//! So long as not deployed in `crates.io`, please notice that all of the information in this crate,
    133//! namely in [`crate::guides`] and such are compatible with the master branch of `pezkuwi-sdk`. A
    134//! few solutions have been proposed to improve this, please see
    135//! [here](https://github.com/pezkuwichain/pezkuwi-sdk/issues/146).
    136//!
    137//! ## How to Develop Locally
    138//!
    139//! To view the docs specific [`crate`] locally for development, including the correct HTML headers
    140//! injected, run:
    141//!
    142//! ```sh
    143//! SKIP_WASM_BUILD=1 \
    144//! RUSTDOCFLAGS="--html-in-header $(pwd)/docs/sdk/assets/header.html --extend-css $(pwd)/docs/sdk/assets/theme.css --default-theme=ayu" \
    145//! cargo doc -p pezkuwi-sdk-docs --no-deps --open
    146//! ```
    147//!
    148//! If even faster build time for docs is needed, you can temporarily remove most of the
    149//! substrate/cumulus dependencies that are only used for linking purposes.
    150//!
    151//! For more on local development, see [`crate::reference_docs::development_environment_advice`].