Skip to content

Welcome to the Substrate developer community

Thank you for your interest in contributing to documentation for the Substrate development framework. As a member of the community, you are invited and encouraged to contribute by submitting issues, offering suggestions for improvements to existing content, adding review comments to existing pull requests, proposing new content, or creating new pull requests to fix issues or provide new content.

We value, respect, and appreciate all contributions from the developer community and only ask that you agree to abide by our Code of conduct and review our Contributor guidelines.

To learn more about how to contribute, including guidelines for how to structure content and how to participate in our bounty program that pays you for contributing, see the following topics:

Before you contribute

Before contributing, take a few minutes to review the contributor guidelines. The contributor guidelines are intended to make the contribution process easy and effective for everyone involved in addressing your issue, assessing changes, and finalizing your pull requests.

Before contributing, consider the following:

  • If you want to report an issue or request help, click Issues. You can also post a message to the community forum, ask a question on StackOverflow, or submit a support request.

  • If you are reporting a bug, provide as much information about the problem as possible, including the version you are using.

  • If you want to contribute directly to this repository, typical fixes might include any of the following:

  • Spelling, grammar, or typo fixes.

  • Code indentation, white space, or formatting changes.
  • Broken or missing links.

Note that any contribution to this repository must be submitted in the form of a pull request. If you are creating a pull request, be sure that the pull request only implements one bug fix.

If you are new to working with GitHub repositories and creating pull requests, consider exploring First Contributions or How to Contribute to an Open Source Project on GitHub.

Basic workflow for all contributions

If you want to contribute in this repository, you should follow the recommended workflow and adhere to the best practices described in this section. Following the recommended workflow helps to ensure that updates and improvements can be integrated smoothly for all contributors and maintainers. Here's a summary of the steps to follow:

  1. Make sure you have a GitHub account, an internet connection, and access to a terminal shell or GitHub Desktop application for running commands.

  2. Clone the repository to your local machine or click Fork to create a copy of the repository under your GitHub account or organization name.

  3. Create a new branch for your fix by running a command similar to the following:

bash git switch -c my-branch-name-here

  1. Open the file you want to fix in a text editor and make the appropriate changes for the issue you are trying to address.

  2. Add the file contents of the changed files to the index git uses to manage the state of the project by running a command similar to the following:

bash git add path-to-changed-file

  1. Commit your changes to store the contents you added to the index along with a descriptive message by running a command similar to the following:

bash git commit -m "Description of the fix being committed."

  1. Push the changes to the remote repository by running a command similar to the following:

bash git push origin my-branch-name-here

  1. Create a new pull request for the branch you pushed to the upstream GitHub repository.

Be sure to provide a title that includes a short description of the changes made.

After you submit the pull request, it needs to be reviewed and approved.

Don't worry if your pull request is not immediately approved, for example, if changes are requested or if a reviewer asks for additional information. Make changes or add comments to the pull request, as needed.

  1. Celebrate your success after your pull request is merged!

Contributor guidelines

The most valuable contributions from the community typically take the form of how-to guides or tutorials that help other developers solve specific problems, learn specific skills, or demonstrate specific tasks.

If you would like to contribute, you might be wondering “What is the difference between a ‘how-to’ guide and a tutorial?”.

How-to guides

A how-to guide describes how to achieve a goal or complete a task. Only the information that is pertinent to achieving that goal or completing the task is included. With how-to guides, readers have enough information to know what they want to do—for example, open a bank account—but not necessarily enough information to know how to do it—for example, 1) select an institution, 2) fill out an application, 3) deposit a minimum amount of currency. How-to guides often include links to additional information, but should not include explanations that take the focus away from what the reader wants to accomplish.

Tutorials

A tutorial is a hands-on illustration or lesson that enables the reader to achieve a highly-predictable result. Tutorials assume that readers have no prior knowledge on the subject being covered and that they require explicit guidance to complete each step to reach a well-known outcome. Typically, a tutorial is a guided tour that helps the reader complete one organic task from start to finish. There are no detours and the information should not be broken out into subtopics because the steps must be completed in order, not in a sequence of the reader’s choosing.

The single most important aspect of a tutorial is that it should always result in a successful, expected outcome. The successful outcome is what inspires confidence and delight in the reader. The single most important distinction between a how-to guide and a tutorial is that in a tutorial the author decides what the goal should be and the author eliminates all distractions that would detract from the successful achievement of the goal.

Recommendations for writing how-to guides

The Substrate Developer Hub is intended to provide a modular and extensible framework of resources for the Substrate developer community and broader ecosystem. To achieve this goal, we want to make it easy for contributors to integrate new content that follows a few guiding principles and basic conventions for structure and style. As a content creator, you should keep the following general principles in mind:

  • ◼️ Modularity. Each guide has a well-defined and useful focus. However, if there’s information that’s useful in more than one guide, you can abstract it into a standalone topic and reuse it in multiple places.

  • 🔗 Linking. Guides should use links where they are useful—for example, to guide readers to concepts or reference topics—but be mindful that stale links frustrate readers.

  • ⏯️ Examples. Useful code examples are a critical component of creating a useful guide.

  • 🛰️ Related references. Guides can include links to related resources, like Rust docs, video content, or other guides and tutorials.

Using the How-to guide template

We recommend you use the how-to guide template to structure articles that you want to submit as to “how-to” topics. You can download a copy of the Markdown template directly from here.

After downloading the template, rename the file and replace the description of each section with the relevant content. The following template outline provides suggestions for the content to put in each section of the how-to guide.

[Guide title]

The guide title should summarize the goal of the article. For “how-to” guides, the title should complete the “How do I …?” sentence.

The first paragraph of the article should provide a brief overview of what the article is about and why this information is useful to its audience. The overview section does not require a heading and it might be more than one paragraph.

The opening section of each article sets the stage for what follows and should answer the obvious questions so readers can decide whether the content is relevant to them. Readers should know—just from reading this section—whether they should continue or the content doesn’t apply to them and they should move on to something else.

For your overview, try to answer the following questions:

  • What is this article about?

  • What is the purpose or goal to be accomplished by following the procedure or technique?

  • Why would someone want to use this procedure or technique? For example, are there specific use case scenarios that are applicable?

  • When would someone use this procedure? For example, is this an activity that is done once or repeated? Is it a pattern or a unique case?

  • Where is the procedure or technique applicable?

  • Who would use this procedure or technique? For example, are special skills required? Do specific permissions or restrictions apply?

The overview section is also a good place to link to other resources, including other guides. As the content creator, you want readers to have confidence that the guide will be useful for them.

Before you begin

This section is optional but recommended. Use the Before you begin heading and use the section body to describe any prerequisites that apply to your article.

This section should answer the following questions:

  • What should someone have before reading this article?

  • What should someone know before reading this article?

  • What should someone do before reading this article?

[Logical name for a set of steps]

Instead of a generic Steps heading, describe what the steps accomplish. For most procedures and techniques, use clear, concise headings to describe each part of the procedure or technique. Use the generic Steps heading only if the article has one set of steps that achieve a single goal. For example, use Steps if an article is tightly focused on a single use case and a more descriptive heading would simply repeat the article title.

For the content in this section:

  • Each step should be action driven. In most cases, each step starts with a verb and ends with a period.

  • The paragraph following a step should describe the result or outcome the reader should expect.

  • If you feel a step needs any additional information, link to that information rather than embedding too much extraneous detail within the step.

  • Code snippets can help illustrate the steps but should not overwhelm the focus on "how do I do this" not on "what do I do".

Keep in mind that most steps have results and readers like confirmation that they have taken the correct action as they progress through a procedure.

Examples

Provide links to one or more code-based examples that make practical use of your article. This section should include at least one reference to a repository that exposes what this guide covers in the form of a working example. You can use reference an existing codebase within Substrate or new code in any publicly-available repository.

This section is optional. If you include it, add a bulleted list of links to similar guides, other Developer Hub ressources, or related material. For example, you might add links to other how-to guides, tutorials, or Rust docs.

Content categories and tags

The How-to guides are grouped into categories to help keep them organized in the how-to-guides repository. The current groupings reflect the different areas of development within Substrate:

  • Basics. Where the really simple guides live, those that can be referenced by more complex ones.

  • Pallet design. Everything to do with building custom pallets with or without FRAME.

  • Weights. Any content that covers configuring weights for specific use cases.

  • Testing. A collection of guides for testing.

  • Storage migrations. Anything to do with storage migrations.

  • Consensus. Consensus models, client-related content, bridging, node configurations.

  • Parachains. Development for projects deploying on Polkadot.

The source files use tags to identify the categories that apply. As a content contributor, you should use tags to identify the level of complexity and the most appropriate category for your content. You can specify the content category for your article by adding one of the following tags:

  • basics
  • client
  • consensus
  • currency
  • fees
  • frame-v1
  • migration
  • node
  • pallet design
  • proof-of-work
  • runtime
  • storage
  • testing
  • weights

Complexity

Specify the level of complexity by adding the most appropriate tag from the following list:

  • beginner
  • intermediate
  • advanced