Vision for Substrate Recipes (v2)

[4meta5]

WHAT ARE THE RECIPES? I envision the recipes as similar to Rust by Example, but for Substrate. The purpose is to provide examples of Substrate runtime patterns through minimal samples. Each sample might only take up a single page in the book, but the point is to demonstrate common patterns and application in the context of an example.

TLDR; each recipe should fulfill two objectives:

• demonstrate Substrate runtime best practices (full code should be tested and placed in kitchen/)
• show the usefulness of the pattern in the context of an example

motivation:

While some developers complete tutorials chronologically, many prefer to skim tutorials for usage examples and apply patterns to build a personal project. For these developers, it is useful to have something like Rust by Example to reference while building. By not requiring the developer to read previous sections for continuity, this format is convenient in the context of fast prototyping based on common design patterns.

If done well, this format can

1. provide high signal to noise for mature developers building on Substrate
2. reduce the friction to publish high-level explanations for code in the SRML

The 2nd objective is especially relevant. I want to minimize the friction for converting personal notes into recipes for teaching others. Moreover, I want to target the creation of specific content pertaining to the most well-vetted code that uses the Substrate Runtime API, the SRML.

srml-tour

With @JoshOrndorff 's blessing, I want to create a section similar to srml-tour for the recipes. I think this fits what I view as the purpose of the recipes: a space to share high-level explanations of SRML code and API usage examples for building runtimes.

criteria

The structure of each recipe should be oriented around the patterns and use cases it exposes. Even so, in general, each recipe should be a single page explainer to communicate how the code in certain module(s) maps to the web3 research specs. Each post should do the following

• motivate study of the chosen module(s) (possibly in the context of Polkadot)
• explain how objects/relationships are modeled and how this influences the implementation
• extract any useful patterns and discuss examples for usage in other runtime samples

priorities

• treasury, especially because of this
• democracy, already partly finished by @JoshOrndorff

• collective + elections as the council
• support/phragmen => elections + staking
• staking because it contains inflation which is interesting paired with treasury and demonstrates fixed point arithmetic

future recipes/sections?

lots of V2 patterns to be covered...

• fixed point arithmetic, see 3456, 3189
• runtime module configuration, see 29
• testing and error handling => not lengthy docs, but succinct tips and short examples of scaffolding (3433 and 3479)

[JoshOrndorff]

@4meta5 Thanks for writing this out so clearly. I'm happy that the srml tour will find a home here. And I'll be ready to write the first recipe in that section next week.

Should we use the existing srml or expand on @shawntabrizi 's idea of a "simple-srml"? Or what do you think about this format for each module. Explore the existing srml module's code noting which parts are the core concepts and which parts are kinda polkadot-specific, then have a recipe for writing a simple version of it.

[shawntabrizi]

Great write up.

I would be interested to learn more about the general structure of the SRML-TOUR

I could see a TON of use of going through each module, and pulling out "recipes" that can be learned from each module. For example:

• Treasury: How to create a pot
• Democracy: How to tally votes or something
• Balances: How to deal with total issuance through imbalances
• etc...

I would see it being a much harder problem to create recipes for "re-creating" the modules. I def see the value in this, but may be ambitious for this round of content development. Maybe the vision?

[4meta5]

@JoshOrndorff Let's stick to the existing SRML for now -- I want to explore the "simple-srml" independent of this (maybe the patterns that we extract from the SRML for this could help us design this simple srml).

I agree with @shawntabrizi -- for now, let's just focus on extracting learned patterns. This is much more realistic than mapping the specs to the module code (although this is also in high demand). I updated the original post -- each module's topics can be organized in the respective issues #33 and #34

If we knock out a bunch of modules with this narrow scope (extract useful patterns), we'll be in a good position to pursue the more ambitious project of documenting how to "re-create" the modules.

[4meta5]

I feel comfortable working towards the structure described in #42