Markdown linter (#1309)

* Add markdown linting - add linter default rules - adapt rules to current code - fix the code for linting to pass - add CI check fix #1243 * Fix markdown for Substrate * Fix tooling install * Fix workflow * Add documentation * Remove trailing spaces * Update .github/.markdownlint.yaml Co-authored-by: Oliver Tale-Yazdi <oliver.tale-yazdi@parity.io> * Fix mangled markdown/lists * Fix captalization issues on known words
2026-06-12 20:31:13 +00:00 · 2023-09-04 11:02:32 +02:00
parent 830fde2a60
commit a30092ab42
271 changed files with 6289 additions and 4450 deletions
@@ -3,4 +3,4 @@ Collection of allocator implementations.
 This crate provides the following allocator implementations:
 - A freeing-bump allocator: [`FreeingBumpHeapAllocator`](https://docs.rs/sc-allocator/latest/sc_allocator/struct.FreeingBumpHeapAllocator.html)

-License: Apache-2.0
+License: Apache-2.0
@@ -1,3 +1,3 @@
 Substrate client interfaces.

-License: GPL-3.0-or-later WITH Classpath-exception-2.0
+License: GPL-3.0-or-later WITH Classpath-exception-2.0
@@ -6,4 +6,4 @@ This crate provides the [`BlockBuilder`] utility and the corresponding runtime a
 The block builder utility is used in the node as an abstraction over the runtime api to
 initialize a block, to push extrinsics and to finalize a block.

-License: GPL-3.0-or-later WITH Classpath-exception-2.0
+License: GPL-3.0-or-later WITH Classpath-exception-2.0
@@ -89,4 +89,4 @@ pub struct Extension {
 pub type MyChainSpec<G> = GenericChainSpec<G, Extension>;
 ```

-License: GPL-3.0-or-later WITH Classpath-exception-2.0
+License: GPL-3.0-or-later WITH Classpath-exception-2.0
@@ -1,3 +1,3 @@
 Substrate CLI library.

-License: GPL-3.0-or-later WITH Classpath-exception-2.0
+License: GPL-3.0-or-later WITH Classpath-exception-2.0
@@ -1,4 +1,4 @@
-Aura (Authority-round) consensus in substrate.
+Aura (Authority-round) consensus in Substrate.

 Aura works by having a list of authorities A who are expected to roughly
 agree on the current time. Time is divided up into discrete slots of t
@@ -12,4 +12,4 @@ far in the future they are.

 NOTE: Aura itself is designed to be generic over the crypto used.

-License: GPL-3.0-or-later WITH Classpath-exception-2.0
+License: GPL-3.0-or-later WITH Classpath-exception-2.0
@@ -45,4 +45,4 @@ blocks) and will go with the longest one in case of a tie.
 An in-depth description and analysis of the protocol can be found here:
 <https://research.web3.foundation/en/latest/polkadot/block-production/Babe.html>

-License: GPL-3.0-or-later WITH Classpath-exception-2.0
+License: GPL-3.0-or-later WITH Classpath-exception-2.0
@@ -1,3 +1,3 @@
 RPC api for babe.

-License: GPL-3.0-or-later WITH Classpath-exception-2.0
+License: GPL-3.0-or-later WITH Classpath-exception-2.0
@@ -1,3 +1,3 @@
 Collection of common consensus specific implementations

-License: GPL-3.0-or-later WITH Classpath-exception-2.0
+License: GPL-3.0-or-later WITH Classpath-exception-2.0
@@ -1,3 +1,3 @@
 Generic utilities for epoch-based consensus engines.

-License: GPL-3.0-or-later WITH Classpath-exception-2.0
+License: GPL-3.0-or-later WITH Classpath-exception-2.0
@@ -1,4 +1,4 @@
-Integration of the GRANDPA finality gadget into substrate.
+Integration of the GRANDPA finality gadget into Substrate.

 This crate is unstable and the API and usage may change.

@@ -36,4 +36,4 @@ number (this is num(signal) + N). When finalizing a block, we either apply
 or prune any signaled changes based on whether the signaling block is
 included in the newly-finalized chain.

-License: GPL-3.0-or-later WITH Classpath-exception-2.0
+License: GPL-3.0-or-later WITH Classpath-exception-2.0
@@ -1,3 +1,3 @@
 RPC API for GRANDPA.

-License: GPL-3.0-or-later WITH Classpath-exception-2.0
+License: GPL-3.0-or-later WITH Classpath-exception-2.0
@@ -1,4 +1,4 @@
 A manual sealing engine: the engine listens for rpc calls to seal blocks and create forks.
 This is suitable for a testing environment.

-License: GPL-3.0-or-later WITH Classpath-exception-2.0
+License: GPL-3.0-or-later WITH Classpath-exception-2.0
@@ -4,4 +4,4 @@ Some consensus algorithms have a concept of *slots*, which are intervals in
 time during which certain events can and/or must occur.  This crate
 provides generic functionality for slots.

-License: GPL-3.0-or-later WITH Classpath-exception-2.0
+License: GPL-3.0-or-later WITH Classpath-exception-2.0
@@ -8,4 +8,4 @@ having discarded heavy state that will allow a chain reorganization.

 Finality implies canonicality but not vice-versa.

-License: GPL-3.0-or-later WITH Classpath-exception-2.0
+License: GPL-3.0-or-later WITH Classpath-exception-2.0
@@ -10,4 +10,4 @@ provided into the wasm runtime module.
 by the current value of `:code` in the provided externalities), i.e. interfacing with
 wasm engine used, instance cache.

-License: GPL-3.0-or-later WITH Classpath-exception-2.0
+License: GPL-3.0-or-later WITH Classpath-exception-2.0
@@ -1,3 +1,3 @@
 A set of common definitions that are needed for defining execution engines.

-License: GPL-3.0-or-later WITH Classpath-exception-2.0
+License: GPL-3.0-or-later WITH Classpath-exception-2.0
@@ -1 +1 @@
-License: GPL-3.0-or-later WITH Classpath-exception-2.0
+License: GPL-3.0-or-later WITH Classpath-exception-2.0
@@ -1,3 +1,3 @@
 Console informant. Prints sync progress and block events. Runs on the calling thread.

-License: GPL-3.0-or-later WITH Classpath-exception-2.0
+License: GPL-3.0-or-later WITH Classpath-exception-2.0
@@ -1,3 +1,3 @@
 Keystore (and session key management) for ed25519 based chains like Polkadot.

-License: GPL-3.0-or-later WITH Classpath-exception-2.0
+License: GPL-3.0-or-later WITH Classpath-exception-2.0
@@ -38,4 +38,4 @@ opens the door for neighbor status packets to be baked into the gossip protocol.
 These status packets will typically contain light pieces of information
 used to inform peers of a current view of protocol state.

-License: GPL-3.0-or-later WITH Classpath-exception-2.0
+License: GPL-3.0-or-later WITH Classpath-exception-2.0
@@ -80,8 +80,8 @@ is "dot". In the protocol names below, `<protocol-id>` must be replaced with the
 protocol ID.

 > **Note**: It is possible for the same connection to be used for multiple chains. For example,
->           one can use both the `/dot/sync/2` and `/sub/sync/2` protocols on the same
->           connection, provided that the remote supports them.
+> one can use both the `/dot/sync/2` and `/sub/sync/2` protocols on the same
+> connection, provided that the remote supports them.

 Substrate uses the following standard libp2p protocols:

@@ -138,7 +138,7 @@ substream is closed, the entire connection is closed as well. This is a bug that
 resolved by deprecating the protocol entirely.

 Within the unique Substrate substream, messages encoded using
-[*parity-scale-codec*](https://github.com/paritytech/parity-scale-codec) are exchanged.
+[`parity-scale-codec``](https://github.com/paritytech/parity-scale-codec) are exchanged.
 The detail of theses messages is not totally in place, but they can be found in the
 `message.rs` file.

@@ -240,7 +240,7 @@ The state is then imported into the database and the keep-up sync starts in norm
 This is similar to fast sync, but instead of downloading and verifying full header chain, the algorithm
 only downloads finalized authority set changes.

-### GRANDPA warp sync.
+### GRANDPA warp sync

 GRANDPA keeps justifications for each finalized authority set change. Each change is signed by the
 authorities from the previous set. By downloading and verifying these signed hand-offs starting from genesis,
@@ -254,7 +254,7 @@ the fast sync. The state is verified to match the header storage root. After the
 database it is queried for the information that allows GRANDPA and BABE to continue operating from that state.
 This includes BABE epoch information and GRANDPA authority set id.

-### Background block download.
+### Background block download

 After the latest state has been imported the node is fully operational, but is still missing historic block
 data. I.e. it is unable to serve bock bodies and headers other than the most recent one. To make sure all
@@ -15,4 +15,4 @@ for instance via:
 2. Majority voting for results
 3. etc

-License: GPL-3.0-or-later WITH Classpath-exception-2.0
+License: GPL-3.0-or-later WITH Classpath-exception-2.0
@@ -1,3 +1,3 @@
 Prometheus basic proposer metrics.

-License: GPL-3.0-or-later WITH Classpath-exception-2.0
+License: GPL-3.0-or-later WITH Classpath-exception-2.0
@@ -1,5 +1,5 @@
 Substrate RPC interfaces.

-A collection of RPC methods and subscriptions supported by all substrate clients.
+A collection of RPC methods and subscriptions supported by all Substrate clients.

-License: GPL-3.0-or-later WITH Classpath-exception-2.0
+License: GPL-3.0-or-later WITH Classpath-exception-2.0
@@ -1,3 +1,3 @@
 Substrate RPC servers.

-License: GPL-3.0-or-later WITH Classpath-exception-2.0
+License: GPL-3.0-or-later WITH Classpath-exception-2.0
@@ -1,5 +1,5 @@
 Substrate RPC interfaces.

-A collection of RPC methods and subscriptions supported by all substrate clients.
+A collection of RPC methods and subscriptions supported by all Substrate clients.

-License: GPL-3.0-or-later WITH Classpath-exception-2.0
+License: GPL-3.0-or-later WITH Classpath-exception-2.0
@@ -2,4 +2,4 @@ Substrate RPC implementation.

 A core implementation of Substrate RPC interfaces.

-License: GPL-3.0-or-later WITH Classpath-exception-2.0
+License: GPL-3.0-or-later WITH Classpath-exception-2.0
@@ -1,4 +1,4 @@
 Substrate service. Starts a thread that spins up the network, client, and extrinsic pool.
 Manages communication between them.

-License: GPL-3.0-or-later WITH Classpath-exception-2.0
+License: GPL-3.0-or-later WITH Classpath-exception-2.0
@@ -2,15 +2,15 @@ State database maintenance. Handles canonicalization and pruning in the database
 this module is a `ChangeSet` which is basically a list of key-value pairs (trie nodes) that
 were added or deleted during block execution.

-# Canonicalization.
+# Canonicalization
 Canonicalization window tracks a tree of blocks identified by header hash. The in-memory
 overlay allows to get any node that was inserted in any of the blocks within the window.
 The tree is journaled to the backing database and rebuilt on startup.
 Canonicalization function selects one root from the top of the tree and discards all other roots and
 their subtrees.

-# Pruning.
+# Pruning
 See `RefWindow` for pruning algorithm details. `StateDb` prunes on each canonicalization until pruning
 constraints are satisfied.

-License: GPL-3.0-or-later WITH Classpath-exception-2.0
+License: GPL-3.0-or-later WITH Classpath-exception-2.0
@@ -1,6 +1,6 @@
 # sc-telemetry

-Substrate's client telemetry is a part of substrate that allows ingesting telemetry data
+Substrate's client telemetry is a part of Substrate that allows ingesting telemetry data
 with for example [Polkadot telemetry](https://github.com/paritytech/substrate-telemetry).

 It works using Tokio's [tracing](https://github.com/tokio-rs/tracing/) library. The telemetry
@@ -9,8 +9,8 @@ tracing `Layer`. This layer will then send the data through an asynchronous chan
 background task called [`TelemetryWorker`] which will send the information to the configured
 remote telemetry servers.

-If multiple substrate nodes are running in the same process, it uses a `tracing::Span` to
-identify which substrate node is reporting the telemetry. Every task spawned using sc-service's
+If multiple Substrate nodes are running in the same process, it uses a `tracing::Span` to
+identify which Substrate node is reporting the telemetry. Every task spawned using sc-service's
 `TaskManager` automatically inherit this span.

 Substrate's nodes initialize/register with the [`TelemetryWorker`] using a [`TelemetryHandle`].
@@ -1,4 +1,4 @@
-Instrumentation implementation for substrate.
+Instrumentation implementation for Substrate.

 This crate is unstable and the API and usage may change.

@@ -8,4 +8,4 @@ See `sp-tracing` for examples on how to use tracing.

 Currently we provide `Log` (default), `Telemetry` variants for `Receiver`

-License: GPL-3.0-or-later WITH Classpath-exception-2.0
+License: GPL-3.0-or-later WITH Classpath-exception-2.0
@@ -232,7 +232,7 @@ are interested in.

 Since the pool is expected to store more transactions than what can fit
 in a single block, validating the entire pool on every block might not be
-feasible. This means that the actual implementation might need to take some 
+feasible. This means that the actual implementation might need to take some
 shortcuts.

 ## Suggestions & caveats
@@ -255,7 +255,7 @@ shortcuts.
   lot of re-orgs. Make sure that transactions are never lost.

 1. The UTXO model is quite challenging. A transaction becomes valid right after
-   it's included in a block, however it is waiting for exactly the same inputs 
+   it's included in a block, however it is waiting for exactly the same inputs
   to be spent, so it will never really be included again.

 1. Note that in a non-ideal implementation the state of the pool will most
@@ -278,7 +278,7 @@ shortcuts.

 1. We periodically validate all transactions in the pool in batches.

-1. To minimize runtime calls, we introduce the batch-verify call. Note it should 
+1. To minimize runtime calls, we introduce the batch-verify call. Note it should
   reset the state (overlay) after every verification.

 1. Consider leveraging finality. Maybe we could verify against latest finalised
@@ -355,7 +355,7 @@ figure out what tags were satisfied by a transaction in that block. For each blo
 transaction we either call into the runtime to get it's `ValidTransaction` object,
 or we check the pool if that transaction is already known to spare the runtime
 call. From this we gather the full set of `provides` tags and perform pruning of
-the `ready` pool based on that. Also, we promote all transactions from `future` 
+the `ready` pool based on that. Also, we promote all transactions from `future`
 that have their tags satisfied.

 In case we remove transactions that we are unsure if they were already included