Umbrella crate: exclude chain-specific crates (#5173)

ggwpez · web-flow · commit 0fb6e3c51eb3 · 2024-08-07T14:30:33.000Z
Uses custom metadata to exclude chain-specific crates. The only concern is that devs who want to use chain-specific crates, still need to select matching versions numbers. Could possibly be addresses with chain-specific umbrella crates, but currently it should be possible to use [psvm](https://github.com/paritytech/psvm). --------- Signed-off-by: Oliver Tale-Yazdi <oliver.tale-yazdi@parity.io>
diff --git a/Cargo.lock b/Cargo.lock
diff --git a/bridges/chains/chain-asset-hub-rococo/Cargo.toml b/bridges/chains/chain-asset-hub-rococo/Cargo.toml
@@ -7,6 +7,9 @@ edition.workspace = true
 license = "GPL-3.0-or-later WITH Classpath-exception-2.0"
 repository.workspace = true
 
+[package.metadata.polkadot-sdk]
+exclude-from-umbrella = true
+
 [lints]
 workspace = true
 
diff --git a/bridges/chains/chain-asset-hub-westend/Cargo.toml b/bridges/chains/chain-asset-hub-westend/Cargo.toml
@@ -7,6 +7,9 @@ edition.workspace = true
 license = "GPL-3.0-or-later WITH Classpath-exception-2.0"
 repository.workspace = true
 
+[package.metadata.polkadot-sdk]
+exclude-from-umbrella = true
+
 [lints]
 workspace = true
 
diff --git a/bridges/chains/chain-bridge-hub-cumulus/Cargo.toml b/bridges/chains/chain-bridge-hub-cumulus/Cargo.toml
@@ -7,6 +7,9 @@ edition.workspace = true
 license = "GPL-3.0-or-later WITH Classpath-exception-2.0"
 repository.workspace = true
 
+[package.metadata.polkadot-sdk]
+exclude-from-umbrella = true
+
 [lints]
 workspace = true
 
diff --git a/bridges/chains/chain-bridge-hub-kusama/Cargo.toml b/bridges/chains/chain-bridge-hub-kusama/Cargo.toml
@@ -7,6 +7,9 @@ edition.workspace = true
 license = "GPL-3.0-or-later WITH Classpath-exception-2.0"
 repository.workspace = true
 
+[package.metadata.polkadot-sdk]
+exclude-from-umbrella = true
+
 [lints]
 workspace = true
 
diff --git a/bridges/chains/chain-bridge-hub-polkadot/Cargo.toml b/bridges/chains/chain-bridge-hub-polkadot/Cargo.toml
@@ -7,6 +7,9 @@ edition.workspace = true
 license = "GPL-3.0-or-later WITH Classpath-exception-2.0"
 repository.workspace = true
 
+[package.metadata.polkadot-sdk]
+exclude-from-umbrella = true
+
 [lints]
 workspace = true
 
diff --git a/bridges/chains/chain-bridge-hub-rococo/Cargo.toml b/bridges/chains/chain-bridge-hub-rococo/Cargo.toml
@@ -7,6 +7,9 @@ edition.workspace = true
 license = "GPL-3.0-or-later WITH Classpath-exception-2.0"
 repository.workspace = true
 
+[package.metadata.polkadot-sdk]
+exclude-from-umbrella = true
+
 [lints]
 workspace = true
 
diff --git a/bridges/chains/chain-bridge-hub-westend/Cargo.toml b/bridges/chains/chain-bridge-hub-westend/Cargo.toml
@@ -7,6 +7,9 @@ edition.workspace = true
 license = "GPL-3.0-or-later WITH Classpath-exception-2.0"
 repository.workspace = true
 
+[package.metadata.polkadot-sdk]
+exclude-from-umbrella = true
+
 [lints]
 workspace = true
 
diff --git a/bridges/chains/chain-kusama/Cargo.toml b/bridges/chains/chain-kusama/Cargo.toml
@@ -7,6 +7,9 @@ edition.workspace = true
 license = "GPL-3.0-or-later WITH Classpath-exception-2.0"
 repository.workspace = true
 
+[package.metadata.polkadot-sdk]
+exclude-from-umbrella = true
+
 [lints]
 workspace = true
 
diff --git a/bridges/chains/chain-polkadot-bulletin/Cargo.toml b/bridges/chains/chain-polkadot-bulletin/Cargo.toml
@@ -7,6 +7,9 @@ edition.workspace = true
 license = "GPL-3.0-or-later WITH Classpath-exception-2.0"
 repository.workspace = true
 
+[package.metadata.polkadot-sdk]
+exclude-from-umbrella = true
+
 [lints]
 workspace = true
 
diff --git a/bridges/chains/chain-rococo/Cargo.toml b/bridges/chains/chain-rococo/Cargo.toml
@@ -7,6 +7,9 @@ edition.workspace = true
 license = "GPL-3.0-or-later WITH Classpath-exception-2.0"
 repository.workspace = true
 
+[package.metadata.polkadot-sdk]
+exclude-from-umbrella = true
+
 [lints]
 workspace = true
 
diff --git a/bridges/chains/chain-westend/Cargo.toml b/bridges/chains/chain-westend/Cargo.toml
@@ -7,6 +7,9 @@ edition.workspace = true
 license = "GPL-3.0-or-later WITH Classpath-exception-2.0"
 repository.workspace = true
 
+[package.metadata.polkadot-sdk]
+exclude-from-umbrella = true
+
 [lints]
 workspace = true
 
diff --git a/docs/contributor/CONTRIBUTING.md b/docs/contributor/CONTRIBUTING.md
@@ -82,6 +82,45 @@ Non "silent" PRs must come with documentation in the form of a `.prdoc` file.
 
 See more about `prdoc` [here](./prdoc.md)
 
+## Crate Configuration `Cargo.toml`
+
+The Polkadot SDK uses many conventions when configuring a crate. Watch out for these things when you
+are creating a new crate.
+
+### Is the Crate chain-specific?
+
+Chain-specific crates, for example
+[`bp-bridge-hub-rococo`](https://github.com/paritytech/polkadot-sdk/blob/4014b9bf2bf8f74862f63e7114e5c78009529be5/bridges/chains/chain-bridge-hub-rococo/Cargo.toml#L10-L11)
+, should not be released as part of the Polkadot-SDK umbrella crate. We have a custom metadata
+attribute that is picked up by the [generate-umbrella.py](../../scripts/generate-umbrella.py)
+script, that should be applied to all chain-specific crates like such:
+
+```toml
+[package]
+# Other stuff...
+
+[package.metadata.polkadot-sdk]
+exclude-from-umbrella = true
+
+# Other stuff...
+```
+
+### Is the Crate a Test, Example or Fuzzer?
+
+Test or example crates, like
+[`pallet-example-task`](https://github.com/paritytech/polkadot-sdk/blob/9b4acf27b869d7cbb07b03f0857763b8c8cc7566/substrate/frame/examples/tasks/Cargo.toml#L9)
+, should not be released to crates.io. To ensure this, you must add `publish = false` to your
+crate's `package` section:
+
+```toml
+[package]
+# Other stuff...
+
+publish = false
+
+# Other stuff...
+```
+
 ## Helping out
 
 We use [labels](https://github.com/paritytech/polkadot-sdk/labels) to manage PRs and issues and communicate state of a
diff --git a/polkadot/runtime/rococo/constants/Cargo.toml b/polkadot/runtime/rococo/constants/Cargo.toml
@@ -6,6 +6,9 @@ authors.workspace = true
 edition.workspace = true
 license.workspace = true
 
+[package.metadata.polkadot-sdk]
+exclude-from-umbrella = true
+
 [lints]
 workspace = true
 
diff --git a/polkadot/runtime/westend/constants/Cargo.toml b/polkadot/runtime/westend/constants/Cargo.toml
@@ -6,6 +6,9 @@ authors.workspace = true
 edition.workspace = true
 license.workspace = true
 
+[package.metadata.polkadot-sdk]
+exclude-from-umbrella = true
+
 [lints]
 workspace = true
 
diff --git a/prdoc/pr_5173.prdoc b/prdoc/pr_5173.prdoc
@@ -0,0 +1,39 @@
+title: "Umbrella crate: exclude chain-specific crates"
+
+doc:
+  - audience: Runtime Dev
+    description: |
+      The `polkadot-sdk` umbrella crate does now not contain chain-specific crates. The reasoning is
+      that the SDK should be mostly chain-agnostic. Please check out
+      [psvm](https://github.com/paritytech/psvm) to select matching version numbers for chain-
+      specific crates.
+
+crates:
+  - name: polkadot-sdk
+    bump: major
+  - name: rococo-runtime-constants
+    bump: none
+  - name: westend-runtime-constants
+    bump: none
+  - name: bp-asset-hub-rococo
+    bump: none
+  - name: bp-asset-hub-westend
+    bump: none
+  - name: bp-bridge-hub-cumulus
+    bump: none
+  - name: bp-bridge-hub-kusama
+    bump: none
+  - name: bp-bridge-hub-polkadot
+    bump: none
+  - name: bp-bridge-hub-rococo
+    bump: none
+  - name: bp-bridge-hub-westend
+    bump: none
+  - name: bp-kusama
+    bump: none
+  - name: bp-polkadot-bulletin
+    bump: none
+  - name: bp-rococo
+    bump: none
+  - name: bp-westend
+    bump: none
diff --git a/scripts/generate-umbrella.py b/scripts/generate-umbrella.py
@@ -24,12 +24,13 @@
 """
 def exclude(crate):
 	name = crate.name
-	if crate.metadata.get("polkadot-sdk.skip-umbrella", False):
+	if crate.metadata.get("polkadot-sdk.exclude-from-umbrella", False):
 		return True
 
 	# No fuzzers or examples:
 	if "example" in name or name.endswith("fuzzer"):
 		return True
+
 	# No runtime crates:
 	if name.endswith("-runtime"):
 		# Note: this is a bit hacky. We should use custom crate metadata instead.
diff --git a/umbrella/Cargo.toml b/umbrella/Cargo.toml
diff --git a/umbrella/src/lib.rs b/umbrella/src/lib.rs
