Polkadot-SDK Umbrella Crate (paritytech#3935)

# Umbrella Crate

The Polkadot-SDK "umbrella" is a crate that re-exports all other
published crates. This makes it
possible to have a very small `Cargo.toml` file that only has one
dependency, the umbrella
crate. This helps with selecting the right combination of crate
versions, since otherwise 3rd
party tools are needed to select a compatible set of versions.

## Features

The umbrella crate supports no-std builds and can therefore be used in
the runtime and node.
There are two main features: `runtime` and `node`. The `runtime` feature
enables all `no-std`
crates, while the `node` feature enables all `std` crates. It should be
used like any other
crate in the repo, with `default-features = false`.

For more fine-grained control, additionally, each crate can be enabled
selectively. The umbrella
exposes one feature per dependency. For example, if you only want to use
the `frame-support`
crate, you can enable the `frame-support` feature.

The umbrella exposes a few more general features:
- `tuples-96`: Needs to be enabled for runtimes that have more than 64
pallets.
- `serde`: Specifically enable `serde` en/decoding support.
- `experimental`: Experimental enable experimental features - should not
yet used in production.
- `with-tracing`: Enable tracing support.
- `try-runtime`, `runtime-benchmarks` and `std`: These follow the
standard conventions.
- `runtime`: As described above, enable all `no-std` crates.
- `node`: As described above, enable all `std` crates.
- There does *not* exist a dedicated docs feature. To generate docs,
enable the `runtime` and
`node` feature. For docs.rs the manifest contains specific configuration
to make it show up
  all re-exports.

There is a specific `zepter` check in place to ensure that the features
of the umbrella are
correctly configured. This check is run in CI and locally when running
`zepter`.

## Generation

The umbrella crate needs to be updated every time when a new crate is
added or removed from the
workspace. It is checked in CI by calling its generation script. The
generation script is
located in `./scripts/generate-umbrella.py` and needs dependency
`cargo_workspace`.

Example: `python3 scripts/generate-umbrella.py --sdk . --version 1.9.0`

## Usage

> Note: You can see a live example in the `staging-node-cli` and
`kitchensink-runtime` crates.

The umbrella crate can be added to your runtime crate like this:

`polkadot-sdk = { path = "../../../../umbrella", features = ["runtime"],
default-features =
false}`

or for a node:

`polkadot-sdk = { path = "../../../../umbrella", features = ["node"],
default-features = false
}`

In the code, it is then possible to bring all dependencies into scope
via:

`use polkadot_sdk::*;`

### Known Issues

The only known issue so far is the fact that the `use` statement brings
the dependencies only
into the outer module scope - not the global crate scope. For example,
the following code would
need to be adjusted:

```rust
use polkadot_sdk::*;

mod foo {
   // This does sadly not compile:
   frame_support::parameter_types! { }

   // Instead, we need to do this (or add an equivalent `use` statement):
   polkadot_sdk::frame_support::parameter_types! { }
}
```

Apart from this, no issues are known. There could be some bugs with how
macros locate their own
re-exports. Please compile issues that arise from using this crate.

## Dependencies

The umbrella crate re-exports all published crates, with a few
exceptions:
- Runtime crates like `rococo-runtime` etc are not exported. This
otherwise leads to very weird
  compile errors and should not be needed anyway.
- Example and fuzzing crates are not exported. This is currently
detected by checking the name
of the crate for these magic words. In the future, it will utilize
custom metadata, as it is
  done in the `rococo-runtime` crate.
- The umbrella crate itself. Should be obvious :)

## Follow Ups
- [ ] Re-writing the generator in Rust - the python script is at its
limit.
- [ ] Using custom metadata to exclude some crates instead of filtering
by names.
- [ ] Finding a way to setting the version properly. Currently its
locked in the CI script.

---------

Signed-off-by: Oliver Tale-Yazdi <oliver.tale-yazdi@parity.io>

.config/lychee.toml

@@ -51,5 +51,6 @@ exclude = [
 	"https://www.reddit.com/r/rust/comments/3spfh1/does_collect_allocate_more_than_once_while/",
 	# 403 rate limited:
 	"https://etherscan.io/block/11090290",
+	"https://subscan.io/",
 	"https://substrate.stackexchange.com/.*",
 ]

.config/zepter.yaml

@@ -25,9 +25,13 @@ workflows:
         '--show-path',
         '--quiet',
       ]
-  # Same as `check`, but with the `--fix` flag.
+  # The umbrella crate uses more features, so we to check those too:
+  check_umbrella:
+    - [ $check.0, '--features=serde,experimental,with-tracing,tuples-96,with-tracing', '-p=polkadot-sdk' ]
+  # Same as `check_*`, but with the `--fix` flag.
   default:
     - [ $check.0, '--fix' ]
+    - [ $check_umbrella.0, '--fix' ]
 
 # Will be displayed when any workflow fails:
 help:

.github/workflows/check-features.yml

@@ -13,7 +13,7 @@ jobs:
       - name: Check
         uses: hack-ink/cargo-featalign-action@bea88a864d6ca7d0c53c26f1391ce1d431dc7f34 # v0.1.1
         with:
-          crate: substrate/bin/node/runtime
+          crate: templates/parachain/runtime/
           features: std,runtime-benchmarks,try-runtime
           ignore: sc-executor
           default-std: true

.github/workflows/checks-quick.yml

@@ -116,3 +116,33 @@ jobs:
         run: |
           echo "Checking markdown formatting. More info: docs/contributor/markdown_linting.md"
           markdownlint --config "$CONFIG" --ignore target .
+  check-umbrella:
+    runs-on: arc-runners-polkadot-sdk
+    timeout-minutes: 10
+    needs: [set-image]
+    container:
+      image: ${{ needs.set-image.outputs.IMAGE }}
+    steps:
+      - uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 # v4.1.0 (22. Sep 2023)
+      - name: install python deps
+        run: |
+          sudo apt-get update && sudo apt-get install -y python3-pip python3
+          pip3 install "cargo-workspace>=1.2.4" toml
+      - name: check umbrella correctness
+        run: |
+          python3 scripts/generate-umbrella.py --sdk . --version 0.1.0
+          cargo +nightly fmt --all
+          if [ -n "$(git status --porcelain)" ]; then
+            cat <<EOF
+          👋 Hello developer! The SemVer information that you declared in the prdoc file did not match what the CI detected.
+
+          Please check the output above and see the following links for more help:
+          - https://github.com/paritytech/polkadot-sdk/blob/master/docs/contributor/prdoc.md#record-semver-changes
+          - https://forum.polkadot.network/t/psa-polkadot-sdk-to-use-semver
+
+          Otherwise feel free to ask in the Merge Request or in Matrix chat.
+          EOF
+
+            git diff
+            exit 1
+          fi