0xMiden / 0xMiden/docs

Add Rust smart contract authoring path and compiler maturity warning

オープン
#289 コメント 0 件 リアクション 0 件 担当者 0 名 GitHub で見る
documentation enhancement
主要言語
TypeScript
スター
10
フォーク
50
平均マージ
22日 23時間
マージ済み PR(30日)
1

説明

## Context

The Build → Smart Contracts section is currently Rust-first, but the planned IA should make the model explicit:

- **Smart Contracts** is the domain.
- **Rust** and **MASM** are authoring paths.
- **Miden Standards** are reusable building blocks used from both authoring paths.

Rust-authored smart contracts are an important onboarding path, but the current Rust compiler should be presented with an appropriate maturity warning so developers understand the tradeoff before relying on it for production-sensitive code.

Related issues:

- `0xMiden/docs#287` tracks Build-facing docs for Miden standards.
- `0xMiden/docs#288` tracks MASM as a dedicated authoring path under Build → Smart Contracts.
- `0xMiden/docs#286` tracks renaming **Core Concepts** to **Reference**.

## Recommendation

Add or clarify a **Rust** authoring path under **Build → Smart Contracts** and include a visible callout near the start of the Rust path.

Suggested callout text:

```md
:::caution Compiler maturity
Rust smart contract support is still under active development and is not yet fully production-ready. Use it with caution for production-sensitive logic, validate generated behavior with tests, and prefer direct MASM when you need precise control over account, note, or transaction-script execution.
:::
```

The exact wording can be tuned with the compiler team, but the docs should clearly set expectations that Rust authoring is useful and supported for development, while the compiler is still maturing.

## Proposed information architecture

Recommended placement inside Smart Contracts:

- `builder/smart-contracts/rust/index.md`
- `builder/smart-contracts/rust/project-structure.md`
- `builder/smart-contracts/rust/accounts.md`
- `builder/smart-contracts/rust/components.md`
- `builder/smart-contracts/rust/storage.md`
- `builder/smart-contracts/rust/testing.md`
- `builder/smart-contracts/rust/compiler-limitations.md`

This can be phased in. If a full IA refactor is too large for the first PR, add the warning callout to the existing Rust-first Smart Contracts overview and first smart contract pages first.

## Content to cover

Minimum first pass:

- What Rust authoring does in Miden: Rust → Wasm → MASM → VM execution/proof.
- When Rust is the right authoring path.
- When direct MASM is safer or more precise.
- Known compiler limitations and unsupported patterns.
- How to inspect or reason about generated MASM where possible.
- How to test Rust-authored account components and scripts.
- Cross-links to MASM docs, compiler reference, and Miden Standards docs.

## Validation requirements

Every Rust example in this section should be validated in a brand-new Docker environment before the PR is opened.

Expected validation path:

- Compile Rust examples against the target published crate versions for versioned v0.14 docs.
- Compile Rust examples against the appropriate local or `next` sources for current/unstable docs when APIs differ.
- Run the smallest available test harness when compilation alone is not enough to validate behavior.
- Run the docs build after ingestion and confirm no new broken links or anchors.
- Update versioned docs when examples describe v0.14 APIs or behavior.

## Scope

- Add or clarify the Rust authoring path under Build → Smart Contracts.
- Add the compiler maturity warning callout.
- Cross-link Rust docs with MASM, Standards, Tutorials, and Compiler reference pages.
- Keep examples executable and grounded in shipped APIs.

## Out of scope

- Changing compiler behavior.
- Replacing MASM docs.
- Documenting every compiler limitation in the first PR if the list needs compiler-team review.

コントリビューションガイド

コントリビューションガイドを開く

調査の方向性

この作業は `builder/smart-contracts/rust/` 下のドキュメントに関するものです。既存の Rust-first Smart Contracts の概要ページと最初のスマートコントラクトのページを確認することから始めてください。適切な導入ファイルにコンパイラの成熟度に関する注意書きを追加します。Docker 環境で Rust の例を検証し、ターゲットのクレートバージョンに対してコンパイルし、ドキュメントビルドを実行して壊れたリンクを確認します。MASM、標準、コンパイラリファレンスページへの相互リンクが追加されていることを確認してください。

索引モデルが issue の本文から書いたものです。

評価

技術スタック
docker, rust, wasm
領域
documentation
issue の種類
ドキュメント
難易度
3/5
見積もり時間
1〜2日
活発さ
停滞
明瞭さ
明確に書かれている
初心者へのやさしさ
55/100

新しい issue をメールで受け取る

初心者向けの GitHub issue を短くまとめたダイジェスト。