adding verbose rustdoc to diff between build-spec and chain-spec-builder

[seemantaggarwal]

Follow up from #7619
Adding a more verbose rustdoc for guidance and difference between chain-spec-builder and build-spec commands under polkadot-omni-node

[iulianbarbu]

Suggested some changes. If we're polishing the docs, I would change as part of this PR the polkadot-omni-node README and suggest there instead of installing chain-spec-builder standalone, to use the chain-spec-builder subcommand.

I would also change the parachain/minimal templates READMEs to rely on polkadot-omni-node chain-spec-builder instead of the standalone chain-spec-builder binary.

[iulianbarbu]

I think we miss to clarify one important thing here. IMO build-spec shouldn't be
used anymore with polkadot-omni-node, and we need to make this clear. I guess my suggestion
below already sounds as a deprecation notice. WDYT about it? I personally wouldn't need reasons
for why build-spec should be used, as a user, if the developers plan to introduce a new cmd that
does what this current subcommand does, in a dedicated way.

Suggested change

	///
	/// The `build-spec` command generates a chain specification from existing
	/// configurations. It is typically used for quickly creating a chainspec for
	/// predefined chains such as `dev`, `local`, or a custom specification.
	/// ## When to Use:
	/// - **Quick and simple** chainspec generation.
	/// - Suitable for **standard setups** where manual edits are acceptable.
	/// - When you need a **basic template** that you can modify later.
	/// - You don’t require extensive modifications or validation.
	/// - You need a **quick** chain spec for a predefined network.
	///
	/// The `build-spec` command relies on pre-existing chain specification described by
	/// runtimes genesis presets, embedded in the nodes that support the `buid-spec`
	/// command. Since `polkadot-omni-node` does not contain any embedded runtime,
	/// and requires a `chain-spec` path to be passed to its `--chain` flag, the command
	/// isn't bringing significant value as it does for other node binaries (e.g. the
	/// `polkadot` binary).
	///
	/// For a more versatile `chain-spec` manipulation experience please check out the
	/// `polkadot-omni-node chain-spec-builder` subcommand.

[seemantaggarwal]

I see it in two parts:

1. We update to reflect the current usage.
2. When we actually plan to deprecate it, which should be in a few days anyway, then we update it to be a deprecation notice. From the current agreement, we are not deprecating it, we are just suggesting to use the other one, said that, poeple can still choose to use it, but we recommend the other one

The new subcommand would not be replicating the build-spec behaviour as it was seen that build-spec was not doing anything significant anyway, rather the new command would aim at helping users achieve the desired result in a better way

[michalkucharczyk]

I would re-phrase the first sentence, it is a bit hard to follow for me, maybe:

	/// The `build-spec` command relies on the chain specification built (hard-coded) into the node binary, and may utilize the genesis presets of the runtimes  also embedded in the nodes that support  this command. 

I think we should explicitly deprecate it with:

#[deprecated(note = "[DEPRECATED] will be removed after [DATE]. [ALTERNATIVE]")]

and remove in future (6 months).
See: https://github.com/paritytech/polkadot-sdk/blob/master/docs/contributor/DEPRECATION_CHECKLIST.md

[michalkucharczyk]

Or maybe we should just delete it? Don't think anybody is using this, as we have no specs hardcoded.

[iulianbarbu]

I am personally for adding the deprecation notice right now, or if not adding it, still apply the merge of my suggestion with michal's. IMO we don't need to document reasons to still use build-spec as an intermediate step because the cutoff for 2503 release has happened already, so in between 2503 and the next stable release we'll for sure want to add the deprecation notice either way. These changes as you propose would not land in 2503 (and would not be visible to users), unless you decide to backport to 2503 the chain-spec-builder subcommand addition, and these docs.

I think it is ideal to work on both deprecation & backport for 2503 (if time allows it), and if not, work towards deprecation at least (which IMO requires just adjusting the docs me and @michalkucharczyk commented about, and maybe some docs for how to achieve adding bootnodes & node key params to existing chain-spec files).

[iulianbarbu]

Or maybe we should just delete it? Don't think anybody is using this, as we have no specs hardcoded.

Zombienet still relies on it to add bootnodes (and maybe node key params?).

[iulianbarbu]

Can we rather mention the chain-spec-builder crates.io docs instead of repeating same things?

Suggested change

	/// The `chain-spec-builder` command provides a more **interactive and flexible**
	/// approach to chainspec creation. It allows for direct modification, validation,
	/// and advanced configuration.
	/// ## When to Use:
	/// - When you need **fine-grained control** over the chain specification.
	/// - If you want to **validate and modify** chainspecs before using them.
	/// - Ideal for **parachains** or advanced network configurations.
	/// - You need to **customize, validate, or interactively configure** the chain spec.
	///
	/// # Summary: Choosing Between `build-spec` and `chain-spec-builder`
	///
	/// | Command | When to Use |
	/// |-----------------------|-------------|
	/// | `build-spec` | If you need a quick, standard chain specification with minimal customization. |
	/// | `chain-spec-builder` | If you need to interactively define, validate, or modify a chain spec with additional parameters. |
	///
	/// `chain-spec-builder` subcommand corresponds to the existing `chain-spec-builder` tool
	/// (https://crates.io/crates/staging-chain-spec-builder), which can be used already standalone.
	/// It provides the same functionality as the tool but bundled with `polkadot-omni-node` to enable
	/// easier access to chain-spec generation, patching, converting to raw or validation, from a single
	/// binary, which can be used as a parachain node too.
	///
	/// For a detailed usage guide please check out the standalone tool's crates.io or docs.rs pages:
	/// - https://crates.io/crates/staging-chain-spec-builder
	/// - https://docs.rs/staging-chain-spec-builder/latest/staging_chain_spec_builder/

[seemantaggarwal]

That is a great suggestion, however I would still keep the difference table from here just to be clear. It makes it easier when making a decision for the user

[iulianbarbu]

I don't think the table helps me. e.g. How does quick/standard chain specification aligns with polkadot-omni-node? To start omni-node you need to generate a chain-spec first, based on a runtime WASM blob, that should be built as well. If users already have a chain spec json file, and they want to modify it, or convert it to raw, I don't see a point in using build spec (just to add bootnodes or node key params, or convert to raw). I think we can document these specific use cases (except converting to raw which is already documented) in chain-spec-builder docs. Users would have to learn to do it with build-spec either way, so if it comes to document such aspects, I would do it just once in chain-spec-builder. WDYT?