Add README.md to umbrella #7600

huntbounty · 2025-02-18T10:13:48Z

Resolves #7536

huntbounty · 2025-02-18T10:30:16Z

Maybe I’m getting ahead of myself on the versioning stuff. 👼

For sprucing up the README 🎀—logos, badges, maybe a few emojis. Could I borrow some from the repo’s README?

ggwpez

Thanks for the initiative. There will be some more reviewers taking a look, so maybe wait for that and then look at the whole feedback in general before changing things.

I asked again internally, and apparently it is better if we write this as Rustdoc and then export it. The difference is that we can actually compile the example to see that it works.
But we can do that as last step. Writing it as markdown is good for now since it renders in github.

ggwpez · 2025-02-18T14:30:25Z

umbrella/README.md

@@ -0,0 +1,95 @@
+# `polkadot-sdk`
+


For sprucing up the README 🎀—logos, badges, maybe a few emojis. Could I borrow some from the repo’s README?

Yes of course. I think having a unified look could even be beneficial. Although the repo readme is probably a bit over the top for our need here 😆

ggwpez · 2025-02-18T14:33:02Z

umbrella/README.md

@@ -0,0 +1,95 @@
+# `polkadot-sdk`
+
+`polkadot-sdk` is an umbrella crate re-exporting all other published crates, except for the example and fuzzing, plus some of the runtime crates like Rococo. Consider it the entry to the whole Polkadot and Substrate ecosystem.


I think the word "umbrella" is not actually that well known in this context. We may need to explain it more first.

You can also omit Rococo, it will be phased out.

ggwpez · 2025-02-18T14:34:17Z

umbrella/README.md

+
+## Versioning
+
+We do a stable release for the SDK quarterly with a version scheme reflecting the release cadence. At the time of writing, the latest version is `stable2412` (released on December 2024). To avoid confusion, we plan to align with the established scheme for the umbrella crate. For example, the next stable version of `polkadot-sdk` will be `2503.0.0`.


Am currently asking the release team on what to do here. Either we go with this, or 0.2503 instead.

I feel like 2503.0.0 might have a better chance of being semver-compatible—a lot more than bug fixes could happen in a 3-month window.

ggwpez · 2025-02-18T14:35:05Z

umbrella/README.md

+
+## Usage
+
+The re-exported crates are grouped under the following feature sets.


I think we dont need to explain all of these features in detail. The big ones like node and runtime should probably be first and then the other ones can go into a dropdown for details.

So the scenarios are as follows.

I want to do the following:

I want to build a node with the umbrella crate (node feature)

I want to build a runtime with the umbrella crate (runtime feature)

I want to have benchmarking in the runtime

I want to use pallet-x, y and z in my runtime

These should be answered in this section.

Yeah, that’s better! 😊

ggwpez · 2025-02-18T14:35:37Z

umbrella/README.md

+
+```toml
+[dependencies]
+polkadot-sdk = { version = "0.12.0", features = ["runtime", "tuples-96"] }


The tuples-96 is only needed for bigger runtimes and is a power-user feature.
Can explain it in some advanced section.

ggwpez · 2025-02-18T14:36:25Z

umbrella/README.md

+
+[features]
+runtime-benchmarks = ["polkadot-sdk/runtime-benchmarks"]
+with-tracing = ["polkadot-sdk/with-tracing"]


The tracing is also power user. Maybe focus on the minimal viable usage here - just a runtime.

ggwpez · 2025-02-18T14:37:18Z

umbrella/README.md

+* fine-grained control over dependencies
+* any suggestions?
+
+In addition to the features above, each re-exported crate is feature-gated individually so that one can control exactly which crates to include. In the contrived example below, only the `frame-support` and `frame-system` crates are needed.


Some context:

This is done to reduce build time in cases where only a small subset of dependencies is needed. The less dependencies you enable - the faster it builds.

kianenigma · 2025-02-19T16:07:23Z

umbrella/README.md

+}
+```
+
+To learn more about building with the Polkadot SDK, you may start with these [guides](https://paritytech.github.io/polkadot-sdk/master/polkadot_sdk_docs/guides/index.html).


Let's link to both this, and docs.polkadot.com.

kianenigma · 2025-02-19T16:07:49Z

umbrella/README.md

+
+Seldomly, if the runtime grows larger than 64 pallets, the trait implementations will no longer apply, then the feature `tuples-96` (or even `tuples-128`) is required (at the cost of increased compile time).
+
+## 🚀 Versioning


Link to https://github.com/paritytech/release-registry/ would be useful.

kianenigma · 2025-02-19T16:09:34Z

umbrella/README.md

+polkadot-sdk = { version = "0.12.0", features = ["frame-support", "frame-system"] }
+```
+
+```rust


It is great that this is a full e2e working example!

What is missing is the fact that there is no connection made between polkadot-sdk and polkadot-sdk-frame, which is also exported as a part of it.

iulianbarbu

High level question: if we're adding an umbrella README, does it make sense to have it in here (polkadot-sdk-docs - reference_docs) too? Thinking about include_str! it to the umbrella_crate.rs. Some existing parts from umbrella_crate.rs might still be relevant for this README, like Known Issues, so we can add them to the README and replace the umbrella_crate.rs entirely. I think the rust code sections from the README will be compiled when building the docs for polkadot-sdk-docs too, so we ensure they are still compiling over time.

huntbounty · 2025-02-20T09:32:00Z

It doesn't feel right to me to describe a language feature as a known issue. It kind of makes it sound like it’s a problem with polkadot-sdk that can be fixed, when it’s really neither. What do you think about this instead?

// `frame_support` and `frame_system` are declared here
use polkadot_sdk::*;

#[frame_support::pallet(dev_mode)]
pub mod pallet {
    // `frame_support` and `frame_system` are imported in the outer module,
    // but are not automatically inherited here. Need to "re-import" to make
    // them available in the inner module.
    use super::*;

If it's what you want here, I could also include a bit about how polkadot-sdk is generated. Anything else you want to bring to the README?

iulianbarbu · 2025-02-20T09:41:22Z

Anything else you want to bring to the README?

No, the thing I was thinking is to merge this README and the umbrella_crate.rs docs from polkadot-sdk-docs. The info in umbrella_crate.rs will be mostly similar to part of the README you're writing - in which case we can drop it and just include_str! this README into it. Don't feel like it is useful to have what's currently in umbrella_crate.rs when seeing this README. What do you guys think? @kianenigma @ggwpez

Add README.md to umbrella

09049d3

ggwpez reviewed Feb 18, 2025

View reviewed changes

Add enhancements to README

8e30f12

kianenigma reviewed Feb 19, 2025

View reviewed changes

iulianbarbu reviewed Feb 19, 2025

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add README.md to umbrella #7600

Add README.md to umbrella #7600

huntbounty commented Feb 18, 2025

huntbounty commented Feb 18, 2025

ggwpez left a comment

ggwpez Feb 18, 2025

ggwpez Feb 18, 2025

ggwpez Feb 18, 2025

huntbounty Feb 20, 2025

ggwpez Feb 18, 2025

kianenigma Feb 19, 2025

huntbounty Feb 20, 2025

ggwpez Feb 18, 2025

ggwpez Feb 18, 2025

ggwpez Feb 18, 2025

kianenigma Feb 19, 2025

kianenigma Feb 19, 2025

kianenigma Feb 19, 2025

iulianbarbu left a comment •

edited

Loading

huntbounty commented Feb 20, 2025

iulianbarbu commented Feb 20, 2025

		@@ -0,0 +1,95 @@
		# `polkadot-sdk`

		`polkadot-sdk` is an umbrella crate re-exporting all other published crates, except for the example and fuzzing, plus some of the runtime crates like Rococo. Consider it the entry to the whole Polkadot and Substrate ecosystem.


		## Versioning

		We do a stable release for the SDK quarterly with a version scheme reflecting the release cadence. At the time of writing, the latest version is `stable2412` (released on December 2024). To avoid confusion, we plan to align with the established scheme for the umbrella crate. For example, the next stable version of `polkadot-sdk` will be `2503.0.0`.


		## Usage

		The re-exported crates are grouped under the following feature sets.


		Seldomly, if the runtime grows larger than 64 pallets, the trait implementations will no longer apply, then the feature `tuples-96` (or even `tuples-128`) is required (at the cost of increased compile time).

		## 🚀 Versioning

Add README.md to umbrella #7600

Are you sure you want to change the base?

Add README.md to umbrella #7600

Conversation

huntbounty commented Feb 18, 2025

huntbounty commented Feb 18, 2025

ggwpez left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

iulianbarbu left a comment • edited Loading

Choose a reason for hiding this comment

huntbounty commented Feb 20, 2025

iulianbarbu commented Feb 20, 2025

iulianbarbu left a comment •

edited

Loading