mirror of
https://github.com/pezkuwichain/pezkuwi-subxt.git
synced 2026-04-26 04:07:57 +00:00
Move all example pallets under examples folder. (#10215)
* Put all examples under one folder Signed-off-by: Jimmy Chu <jimmychu0807@gmail.com> * Updated Cargo.toml Signed-off-by: Jimmy Chu <jimmychu0807@gmail.com> * updated for ci script Signed-off-by: Jimmy Chu <jimmychu0807@gmail.com> * update Signed-off-by: Jimmy Chu <jimmychu0807@gmail.com> * Added notes that example pallets are not meant to be used in production. Signed-off-by: Jimmy Chu <jimmychu0807@gmail.com> * updated Signed-off-by: Jimmy Chu <jimmychu0807@gmail.com>
This commit is contained in:
Jimmy Chu
@@ -0,0 +1,240 @@
|
||||
<!-- markdown-link-check-disable -->
|
||||
# Basic Example Pallet
|
||||
|
||||
<!-- Original author of paragraph: @gavofyork -->
|
||||
The Example: A simple example of a FRAME pallet demonstrating
|
||||
concepts, APIs and structures common to most FRAME runtimes.
|
||||
|
||||
Run `cargo doc --package pallet-example-basic --open` to view this pallet's documentation.
|
||||
|
||||
**This pallet serves as an example and is not meant to be used in production.**
|
||||
|
||||
### Documentation Guidelines:
|
||||
|
||||
<!-- Original author of paragraph: Various. Based on collation of review comments to PRs addressing issues with -->
|
||||
<!-- label 'S3-FRAME' in https://github.com/paritytech/substrate-developer-hub/issues -->
|
||||
<ul>
|
||||
<li>Documentation comments (i.e. <code>/// comment</code>) - should
|
||||
accompany pallet functions and be restricted to the pallet interface,
|
||||
not the internals of the pallet implementation. Only state inputs,
|
||||
outputs, and a brief description that mentions whether calling it
|
||||
requires root, but without repeating the source code details.
|
||||
Capitalize the first word of each documentation comment and end it with
|
||||
a full stop. See
|
||||
<a href="https://github.com/paritytech/substrate#72-contributing-to-documentation-for-substrate-packages"
|
||||
target="_blank"> Generic example of annotating source code with documentation comments</a></li>
|
||||
<li>Self-documenting code - Try to refactor code to be self-documenting.</li>
|
||||
<li>Code comments - Supplement complex code with a brief explanation, not every line of code.</li>
|
||||
<li>Identifiers - surround by backticks (i.e. <code>INHERENT_IDENTIFIER</code>, <code>InherentType</code>,
|
||||
<code>u64</code>)</li>
|
||||
<li>Usage scenarios - should be simple doctests. The compiler should ensure they stay valid.</li>
|
||||
<li>Extended tutorials - should be moved to external files and refer to.</li>
|
||||
<!-- Original author of paragraph: @AmarRSingh -->
|
||||
<li>Mandatory - include all of the sections/subsections where <b>MUST</b> is specified.</li>
|
||||
<li>Optional - optionally include sections/subsections where <b>CAN</b> is specified.</li>
|
||||
</ul>
|
||||
|
||||
### Documentation Template:<br>
|
||||
|
||||
Copy and paste this template from frame/examples/basic/src/lib.rs into file
|
||||
`frame/<INSERT_CUSTOM_PALLET_NAME>/src/lib.rs` of your own custom pallet and complete it.
|
||||
<details><p><pre>
|
||||
// Add heading with custom pallet name
|
||||
|
||||
\# <INSERT_CUSTOM_PALLET_NAME> Pallet
|
||||
|
||||
// Add simple description
|
||||
|
||||
// Include the following links that shows what trait needs to be implemented to use the pallet
|
||||
// and the supported dispatchables that are documented in the Call enum.
|
||||
|
||||
- \[`<INSERT_CUSTOM_PALLET_NAME>::Config`](https://docs.rs/pallet-example-basic/latest/pallet_example_basic/trait.Config.html)
|
||||
- \[`Call`](https://docs.rs/pallet-example-basic/latest/pallet_example_basic/enum.Call.html)
|
||||
- \[`Module`](https://docs.rs/pallet-example-basic/latest/pallet_example_basic/struct.Module.html)
|
||||
|
||||
\## Overview
|
||||
|
||||
<!-- Original author of paragraph: Various. See https://github.com/paritytech/substrate-developer-hub/issues/44 -->
|
||||
// Short description of pallet's purpose.
|
||||
// Links to Traits that should be implemented.
|
||||
// What this pallet is for.
|
||||
// What functionality the pallet provides.
|
||||
// When to use the pallet (use case examples).
|
||||
// How it is used.
|
||||
// Inputs it uses and the source of each input.
|
||||
// Outputs it produces.
|
||||
|
||||
<!-- Original author of paragraph: @Kianenigma in PR https://github.com/paritytech/substrate/pull/1951 -->
|
||||
<!-- and comment https://github.com/paritytech/substrate-developer-hub/issues/44#issuecomment-471982710 -->
|
||||
|
||||
\## Terminology
|
||||
|
||||
// Add terminology used in the custom pallet. Include concepts, storage items, or actions that you think
|
||||
// deserve to be noted to give context to the rest of the documentation or pallet usage. The author needs to
|
||||
// use some judgment about what is included. We don't want a list of every storage item nor types - the user
|
||||
// can go to the code for that. For example, "transfer fee" is obvious and should not be included, but
|
||||
// "free balance" and "reserved balance" should be noted to give context to the pallet.
|
||||
// Please do not link to outside resources. The reference docs should be the ultimate source of truth.
|
||||
|
||||
<!-- Original author of heading: @Kianenigma in PR https://github.com/paritytech/substrate/pull/1951 -->
|
||||
|
||||
\## Goals
|
||||
|
||||
// Add goals that the custom pallet is designed to achieve.
|
||||
|
||||
<!-- Original author of heading: @Kianenigma in PR https://github.com/paritytech/substrate/pull/1951 -->
|
||||
|
||||
\### Scenarios
|
||||
|
||||
<!-- Original author of paragraph: @Kianenigma. Based on PR https://github.com/paritytech/substrate/pull/1951 -->
|
||||
|
||||
\#### <INSERT_SCENARIO_NAME>
|
||||
|
||||
// Describe requirements prior to interacting with the custom pallet.
|
||||
// Describe the process of interacting with the custom pallet for this scenario and public API functions used.
|
||||
|
||||
\## Interface
|
||||
|
||||
\### Supported Origins
|
||||
|
||||
// What origins are used and supported in this pallet (root, signed, none)
|
||||
// i.e. root when <code>\`ensure_root\`</code> used
|
||||
// i.e. none when <code>\`ensure_none\`</code> used
|
||||
// i.e. signed when <code>\`ensure_signed\`</code> used
|
||||
|
||||
<code>\`inherent\`</code> <INSERT_DESCRIPTION>
|
||||
|
||||
<!-- Original author of paragraph: @Kianenigma in comment -->
|
||||
<!-- https://github.com/paritytech/substrate-developer-hub/issues/44#issuecomment-471982710 -->
|
||||
|
||||
\### Types
|
||||
|
||||
// Type aliases. Include any associated types and where the user would typically define them.
|
||||
|
||||
<code>\`ExampleType\`</code> <INSERT_DESCRIPTION>
|
||||
|
||||
<!-- Original author of paragraph: ??? -->
|
||||
|
||||
// Reference documentation of aspects such as `storageItems` and `dispatchable` functions should only be
|
||||
// included in the https://docs.rs Rustdocs for Substrate and not repeated in the README file.
|
||||
|
||||
\### Dispatchable Functions
|
||||
|
||||
<!-- Original author of paragraph: @AmarRSingh & @joepetrowski -->
|
||||
|
||||
// A brief description of dispatchable functions and a link to the rustdoc with their actual documentation.
|
||||
|
||||
// <b>MUST</b> have link to Call enum
|
||||
// <b>MUST</b> have origin information included in function doc
|
||||
// <b>CAN</b> have more info up to the user
|
||||
|
||||
\### Public Functions
|
||||
|
||||
<!-- Original author of paragraph: @joepetrowski -->
|
||||
|
||||
// A link to the rustdoc and any notes about usage in the pallet, not for specific functions.
|
||||
// For example, in the Balances Pallet: "Note that when using the publicly exposed functions,
|
||||
// you (the runtime developer) are responsible for implementing any necessary checks
|
||||
// (e.g. that the sender is the signer) before calling a function that will affect storage."
|
||||
|
||||
<!-- Original author of paragraph: @AmarRSingh -->
|
||||
|
||||
// It is up to the writer of the respective pallet (with respect to how much information to provide).
|
||||
|
||||
\#### Public Inspection functions - Immutable (getters)
|
||||
|
||||
// Insert a subheading for each getter function signature
|
||||
|
||||
\##### <code>\`example_getter_name()\`</code>
|
||||
|
||||
// What it returns
|
||||
// Why, when, and how often to call it
|
||||
// When it could panic or error
|
||||
// When safety issues to consider
|
||||
|
||||
\#### Public Mutable functions (changing state)
|
||||
|
||||
// Insert a subheading for each setter function signature
|
||||
|
||||
\##### <code>\`example_setter_name(origin, parameter_name: T::ExampleType)\`</code>
|
||||
|
||||
// What state it changes
|
||||
// Why, when, and how often to call it
|
||||
// When it could panic or error
|
||||
// When safety issues to consider
|
||||
// What parameter values are valid and why
|
||||
|
||||
\### Storage Items
|
||||
|
||||
// Explain any storage items included in this pallet
|
||||
|
||||
\### Digest Items
|
||||
|
||||
// Explain any digest items included in this pallet
|
||||
|
||||
\### Inherent Data
|
||||
|
||||
// Explain what inherent data (if any) is defined in the pallet and any other related types
|
||||
|
||||
\### Events:
|
||||
|
||||
// Insert events for this pallet if any
|
||||
|
||||
\### Errors:
|
||||
|
||||
// Explain what generates errors
|
||||
|
||||
\## Usage
|
||||
|
||||
// Insert 2-3 examples of usage and code snippets that show how to
|
||||
// use <INSERT_CUSTOM_PALLET_NAME> Pallet in a custom pallet.
|
||||
|
||||
\### Prerequisites
|
||||
|
||||
// Show how to include necessary imports for <INSERT_CUSTOM_PALLET_NAME> and derive
|
||||
// your pallet configuration trait with the `INSERT_CUSTOM_PALLET_NAME` trait.
|
||||
|
||||
\```rust
|
||||
use <INSERT_CUSTOM_PALLET_NAME>;
|
||||
|
||||
pub trait Config: <INSERT_CUSTOM_PALLET_NAME>::Config { }
|
||||
\```
|
||||
|
||||
\### Simple Code Snippet
|
||||
|
||||
// Show a simple example (e.g. how to query a public getter function of <INSERT_CUSTOM_PALLET_NAME>)
|
||||
|
||||
\### Example from FRAME
|
||||
|
||||
// Show a usage example in an actual runtime
|
||||
|
||||
// See:
|
||||
// - Substrate TCR https://github.com/parity-samples/substrate-tcr
|
||||
// - Substrate Kitties https://shawntabrizi.github.io/substrate-collectables-workshop/#/
|
||||
|
||||
\## Genesis Config
|
||||
|
||||
<!-- Original author of paragraph: @joepetrowski -->
|
||||
|
||||
\## Dependencies
|
||||
|
||||
// Dependencies on other FRAME pallets and the genesis config should be mentioned,
|
||||
// but not the Rust Standard Library.
|
||||
// Genesis configuration modifications that may be made to incorporate this pallet
|
||||
// Interaction with other pallets
|
||||
|
||||
<!-- Original author of heading: @AmarRSingh -->
|
||||
|
||||
\## Related Pallets
|
||||
|
||||
// Interaction with other pallets in the form of a bullet point list
|
||||
|
||||
\## References
|
||||
|
||||
<!-- Original author of paragraph: @joepetrowski -->
|
||||
|
||||
// Links to reference material, if applicable. For example, Phragmen, W3F research, etc.
|
||||
// that the implementation is based on.
|
||||
</pre></p></details>
|
||||
|
||||
License: Unlicense
|
||||
Reference in New Issue
Block a user